错误跟踪
支持平台

1.1 XteVision Error Tracker 是什么？

XteVision Error Tracker（xtevision-error-tracker v1.2.6）是一个厂商中立、完全离线、自托管的完整栈 Web 应用程序，用于管理错误案例、支持工单、项目分配和人员调度。它被设计为可重新品牌化，由任何公司——制造业、自动化或服务型组织——在其自有硬件上运行，无需依赖外部云。

1.2 核心能力

• 错误案例管理：跨工业设备（计量系统、施胶系统、阀门、泵等）跟踪硬件/软件错误，支持完整的根因分析、严重度跟踪和解决方案文档化
• 公开工单接收：通过面向公众的表单接收外部客户的支持工单，然后在内部管理和解决它们
• 项目及人员调度：管理项目分配，跟踪现场人员部署（出行日期、时长、工作描述），并将它们与项目和错误案例关联
• 双服务器同步：基于局域网的内部服务器与面向公众的接收服务器同步工单，并回推状态更新
• AI 知识助手：浮动聊天机器人，基于嵌入的相似案例搜索和客户端翻译
• 多语言界面：data-lang-* 属性支持 EN/DE/ZH/… 在客户端进行翻译
• 可定制的分类体系：组件结构、故障类型和人员列表由简单的配置文件驱动

1.3 目标用户

• 主要用户：任何安装和支持工业设备、需要一个集中系统来处理错误案例、工单和现场调度的公司
• 次要用户：向客户现场派遣人员的服务和维护团队，需要将现场工作与错误案例和项目关联

1.4 白标化

该应用程序出厂时不带任何第三方品牌。更改产品名称、替换标志，并在配置中设置您自己的公司名称、公共服务器 URL 和 API 密钥。所有品牌字符串都集中在少量位置（见部署），使单一公司能够几分钟内重新品牌化该平台。

2.1 高层架构

┌─────────────────────────────────────────────────────────────────┐
│                         浏览器（客户端）                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              原生 HTML/CSS/JS（单页应用）                   │  │
│  │  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────┐  │  │
│  │  │ 登录  │ │ 项目 │ 案例  │ 工单 │ 人员 │  │  │
│  │  └────────┘ └──────────┘ └────────┘ └────────┘ └──────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/REST API
┌──────────────────────────────┴──────────────────────────────────┐
│                    局域网服务器 —— Express.js（端口 5003）         │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐  │
│  │ 认证   │ │ 工单 │ │ 案例  │ │ 人员  │ │ AI（翻译 │  │
│  │        │ │ 同步   │ │ CRUD  │ │ CRUD  │ │ + 相似案例）│  │
│  └────────┘ └────────┘ └────────┘ └────────┘ └──────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    ┌──────────┴──────────┐
                    │  MySQL 8.0（mysql2） │
                    │  error_tracker       │
                    │  8 个核心表          │
                    └─────────────────────┘

        ┌──────────────────────────────────────────────────────────┐
        │  公共服务器（工单接收）                                  │
        │  HTTPS 表单 → 存储工单 → 由局域网服务器同步              │
        └──────────────────────────────────────────────────────────┘

2.2 通信流程

1. 前端 → 局域网服务器：对所有 CRUD 操作和 AI 辅助功能使用发往 Express.js 路由的 RESTful HTTP 请求
2. 局域网服务器 → 数据库：通过 mysql2 使用原始 SQL 查询——全程使用参数化查询
3. 局域网服务器 → 公共服务器：周期性同步将本地状态更新推送到公共服务器，并获取新的公共工单
4. 前端 → AI 后端：翻译和相似案例搜索使用本地 Ollama 实例

2.3 部署模型

XteVision Error Tracker 专为自托管、完全离线运行而设计：

• 作为独立的 Node.js 服务器运行在您自有硬件上
• MySQL 位于 localhost，端口 3306，数据库：error_tracker
• 所有数据都保留在您的本地服务器上——无云依赖
• 公共接收服务器是可选的，可配置为您自己的域名

4.1 前置条件

• MySQL 8.0 已在目标服务器上运行
• Node.js（用于运行 Express 服务器）
• 现代浏览器（Chrome/Edge/Firefox）
• 本地 LLM 服务器（可选，用于 AI 助手功能）

4.2 安装（3 步）

安装依赖并启动服务器。服务器从项目根目录提供静态文件，并在 /api/* 暴露 API。

# 1. 安装依赖
npm install

# 2. 启动服务器（端口 5003）
npm start
# 或：node server.js

4.3 访问应用程序

http://your-server-ip:5003

局域网服务器默认运行在端口 5003。从您的内部网络连接。

4.4 首次配置

1. 配置数据库：创建 error_tracker 数据库并应用来自 backup.sql 的 schema
2. 设置凭据：使用您自己的数据库密码、JWT 密钥以及（如果使用）公共服务器 API 密钥编辑 db.js 和 routes/auth.js——将这些移动到 .env 文件
3. 配置分类体系：编辑 components.json 和 new_parameters/*.txt 以匹配您的设备和故障分类
4. 打开应用：通过 index.html 登录并开始添加项目、案例和工单

5.1 目录结构

xtevision-error-tracker/
├── server.js                 # 主 Express 服务器：路由、认证、上传、AI、静态
├── db.js                     # MySQL 连接单例
├── routes/
│   ├── auth.js               # 用户注册和登录端点
│   ├── users.js              # 用户列表端点（用于下拉框）
│   └── tickets.js            # 工单 CRUD、公共服务器同步、推送到公共
├── index.html                # 主单页应用 —— 登录、项目、任务、案例、工单
├── register.html             # 公开用户注册页面
├── register.js               # 客户端注册逻辑
├── styles.css                # 完整样式表 —— 深色/浅色主题、响应式、动画
├── components.json           # 分层组件分类体系
├── new_parameters/           # 下拉选项列表（集成商、故障类型、…）
├── backup.sql                # 数据库的完整 MySQL 转储
└── license.txt               # 专有许可证协议

5.2 关键文件

6.1 核心表

8.1 认证与安全

基于 JWT 的认证，具有以下机制：

• 令牌过期：8 小时 JWT 生命周期
• 密码哈希：bcrypt，成本因子为 10
• 认证中间件：authenticateToken 检查 Authorization: Bearer <token> 头
• SQL 注入防护：全程使用参数化查询；排序字段使用白名单方法

8.2 文件上传

• 案例附件存储在 uploads/case_<id>/，使用时间戳文件名
• 工单附件存储在 uploads/（从公共服务器同步）和 web_tickets/uploads/（公开表单上传）
• 两个 express.static 挂载覆盖 /uploads 两个目录

8.3 翻译功能

• 客户端翻译链接触发 POST /api/translate → Ollama aya-expanse:8b
• 支持的目标语言：de、en、ru、es、jp、fr、th、vt

8.4 AI 知识助手

• POST /api/ai/find-similar-cases —— 使用 nomic-embed-text 为工单的标题/描述生成嵌入，然后通过余弦相似度找到最相似的 Top-N 错误案例
• 嵌入存储在数据库中以供复用

8.5 公共服务器同步

routes/tickets.js 导出 syncTicketsFromPublicServer()，其功能包括：

1. 将本地工单更新（状态变更，带 sync_required = 1）推送到公共服务器
2. 获取所有公共工单并在本地导入新的工单（通过匹配 customer_name + subject + created_at）
3. 下载并存储来自公共服务器的附件

对工单的状态更新会自动设置 sync_required = 1 以用于回推。

8.6 双服务器通信

• 公共服务器 URL 可配置为您自己的域名（默认占位符：https://error-tracker.example.com）
• 推送 API 密钥可配置——上线前更改为您自己的密钥

9.1 本地 LLM 后端

所有 AI 功能都在本地 Ollama 实例上运行，将客户数据完全保留在私有环境内：

• 翻译：aya-expanse:8b 用于客户端界面翻译
• 嵌入：nomic-embed-text:latest 用于相似案例搜索
• 可选：核心跟踪/工单功能无需 AI 后端即可工作

9.2 相似案例搜索

10.1 要求

• Node.js（用于运行 Express 服务器）
• MySQL 8.0（通过 mysql2）
• 本地 LLM 服务器（可选，用于 AI 助手功能）

10.2 启动应用

# 安装依赖
npm install

# 启动服务器（端口 5003）
npm start
# 或：node server.js

10.3 配置

重新品牌化清单：在 index.html 中设置您自己的产品名称和标志，将公共服务器 URL 替换为您自己的域名，并轮换 JWT 密钥和公共服务器 API 密钥。然后将所有密钥移动到 .env 文件。

10.4 升级到新版本

# 1. 停止服务器
npm stop

# 2. 备份您的数据和配置
cp backup.sql /tmp/et-backup.sql
cp db.js /tmp/et-db.bak

# 3. 安装新版本，然后恢复配置
npm install

# 4. 重启
npm start

升级前始终备份 backup.sql（您的数据）和 db.js / routes/auth.js（您的凭据）。

v1.2.6 — 当前版本

• 错误案例管理：约 40 字段的错误报告，包含根因分析、严重度跟踪、解决方案和经验教训
• 公开工单接收：公共表单，带双服务器同步和状态更新回推
• 人员调度：与项目和错误案例关联的部署跟踪
• AI 知识助手：基于嵌入的相似案例搜索和客户端翻译
• 文件附件：案例和工单附件，带时间戳文件名
• 多语言界面：通过 data-lang-* 属性进行 EN/DE/ZH/… 翻译
• 自定义分类体系：设备结构和故障类型由配置文件驱动
• 白标就绪：无第三方品牌——几分钟内重新品牌化

12.1 服务器无法启动

• 问题：端口已被占用
• 解决方案：更改端口或终止现有进程，然后重启。

12.2 数据库连接失败

• 问题：MySQL 出现“Connection refused”（连接被拒绝）
• 解决方案：验证 MySQL 是否正在运行。检查 db.js 凭据。确保 error_tracker 数据库存在。重新应用来自 backup.sql 的 schema。

12.3 登录后数据不可见

• 问题：登录后页面显示为空
• 解决方案：验证用户是否具有正确的角色，并确认已应用 schema。检查 db.js 中的数据库连接。

12.4 AI 聊天无响应

• 问题：出现“Connection refused”（连接被拒绝）或 AI 无响应
• 解决方案：确保本地 Ollama 服务器正在运行，并已拉取模型（aya-expanse:8b / nomic-embed-text:latest）。AI 功能是可选的——核心跟踪无需它即可工作。

12.5 同步不工作

• 问题：公共工单未被导入或状态未被推送
• 解决方案：验证 routes/tickets.js 中的公共服务器 URL 和 API 密钥。检查网络连通性，并确认状态更新设置了 sync_required = 1。

12.6 附件未显示

• 问题：上传后文件丢失
• 解决方案：验证 uploads/ 目录是否存在并具有写权限。检查上传 API 路由，并确认已配置 multer 中间件。