# HANDOFF — 平台版本号与操作日志子模块 + Docker 部署迁移

> 最后更新：2026-07-29 10:40 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：czj

---

## 1. 我们在做什么

### 1.1 本次会话主要任务

为运行维护平台补充两个功能：

1. **平台版本号显示** — 导航栏右侧显示当前版本号标签（如 `v0.1.0`），数据来自后端 `/api/version` 接口
2. **三个模块的操作日志子模块** — 问题排查、服务监测、服务管理各自独立的操作日志页面，记录用户搜索、分析、导出、巡检执行等操作

### 1.2 Docker 部署迁移

用户反馈当前服务器部署目录不对：
- 原目录：`/opt/troubleshoot-docker`
- 正确目录：`/data/third_party/monitor-platform`

已完成目录迁移和重新部署。

### 1.3 Docker 容器巡检环境隔离问题

用户指出：容器化部署下，本级巡检脚本在容器内执行，获取的是容器虚拟环境数据（CPU/内存/磁盘），而非宿主机真实数据。已输出需求文档和计划执行文档，待后续实施。

---

## 2. 已经完成了什么

### 2.1 平台版本号与操作日志功能 ✅

| 子任务 | 状态 | 验证结果 |
|--------|------|----------|
| 后端 `/api/version` 接口 | ✅ | `curl http://192.168.5.60:8088/api/version` 返回 `v0.1.0` |
| 后端 `/api/audit/logs` 接口 | ✅ | 分页查询、筛选正常 |
| 后端 `/api/audit/users` 接口 | ✅ | 返回有操作记录的用户列表 |
| 后端 `/api/audit/actions/<module>` 接口 | ✅ | 返回模块操作类型列表 |
| 前端 `AppVersion.vue` 组件 | ✅ | 导航栏显示版本号 |
| 前端 `troubleshoot/Logs.vue` | ✅ | 问题排查操作日志页 |
| 前端 `service-monitor/Logs.vue` | ✅ | 服务监测操作日志页 |
| 前端 `service-manage/Logs.vue` | ✅ | 服务管理操作日志页 |
| 侧边栏菜单集成 | ✅ | 三个模块侧边栏均有"操作日志"入口 |
| 后端单元测试 | ✅ | 218 passed |
| 前端构建 | ✅ | `npm run build` 成功 |

### 2.2 Docker 部署迁移 ✅

| 步骤 | 状态 | 说明 |
|------|------|------|
| 停止旧容器 | ✅ | `docker stop troubleshoot && docker rm troubleshoot` |
| 创建目标目录 | ✅ | `/data/third_party/monitor-platform` |
| 迁移数据 | ✅ | 从 `/opt/troubleshoot-docker` 复制 |
| 上传新代码 | ✅ | 通过 `deploy/deploy_docker.py` 上传 |
| 构建镜像 | ✅ | `docker build -t troubleshoot:latest .` |
| 启动容器 | ✅ | 端口 8088，volume 挂载正确 |

### 2.3 部署验证 ✅

```
健康检查：357 条知识库，服务正常
版本 API：/api/version 返回 0.1.0
登录：admin/Ubains@1357 登录成功
审计日志：记录登录、搜索等操作
前端：Vue SPA 正常返回
```

### 2.4 操作日志模块修复 ✅

**问题**：访问操作日志提示"模块不存在"

**原因**：`Logs.vue` 的 `module` prop 没有默认值，路由又没传 prop，导致请求 `/api/audit/actions/undefined`

**修复**：给每个 Logs.vue 通过 `withDefaults` 设置默认值：
- `troubleshoot/Logs.vue` → `module: 'troubleshoot'`
- `service-monitor/Logs.vue` → `module: 'monitor'`
- `service-manage/Logs.vue` → `module: 'manage'`

### 2.5 登录门户卡片标题修改 ✅

将平台首页模块卡片标题从"问题排查助手"改为"运行维护平台"

### 2.6 Docker 容器巡检问题文档 ✅

已输出：
- `Docs/需求文档/PRD_Docker容器巡检环境隔离问题.md`
- `Docs/需求文档/计划执行_Docker容器巡检环境隔离问题.md`

---

## 3. 当前卡在哪

**无卡点**。版本号和操作日志功能已完成并部署，Docker 巡检问题已输出文档待后续实施。

等待用户确认下一步：
1. 是否立即实施 Docker 巡检环境隔离问题修复？
2. 是否提交本次代码变更？

---

## 4. 下一步计划

| 优先级 | 任务 | 说明 |
|--------|------|------|
| **P1** | 实施本级巡检 SSH 到宿主机 | 按 `计划执行_Docker容器巡检环境隔离问题.md` 执行 |
| **P2** | 提交本次代码变更 | git commit 版本号 + 操作日志 + Docker 部署迁移 |
| **P3** | 清理旧部署目录 | `/opt/troubleshoot-docker` 是否删除？ |

---

## 5. 踩过的坑（绝对不要再踩）

### 坑 1：SSE 流式接口 session 脱离请求上下文

**坑**：在 `analyze_stream()` 的 `generate()` 生成器内部访问 `session.get('user', {})` 时，生成器延迟执行已脱离请求上下文，导致 `RuntimeError: Working outside of request context`。

**原因**：Flask 的 request context 只在请求处理期间有效，生成器 yield 时请求已结束。

**避免方法**：在请求上下文内提前捕获 session 数据：
```python
_audit_user = session.get('user', {}).get('username', '')
_audit_ip = request.remote_addr or ''
# 然后在生成器内使用 _audit_user、_audit_ip 而非 session
```

### 坑 2：Vue 组件 prop 无默认值导致 API 报错

**坑**：三个 Logs.vue 定义了 `module` prop 但没默认值，路由又没传 prop，导致请求 `/api/audit/actions/undefined`。

**原因**：TypeScript 的 `defineProps<{ module: ... }>()` 没有默认值时，prop 是 `undefined`。

**避免方法**：使用 `withDefaults` 设置默认值：
```typescript
const props = withDefaults(defineProps<{
  module?: 'troubleshoot' | 'monitor' | 'manage'
}>(), {
  module: 'troubleshoot',  // 默认值
})
```

### 坑 3：admin 账号被错误密码锁定

**坑**：多次错误登录尝试后，admin 账号被内存中的 `login_attempts` 锁定，导致正确密码也无法登录。

**原因**：`auth.py` 有 `_is_locked()` 检查，失败登录次数过多会锁定账号，锁定状态存储在内存中，重启后才清空。

**避免方法**：
- 测试登录时使用正确密码
- 锁定后重启容器清空内存状态
- 或检查 `login_attempts` 字典手动清除

### 坑 4：Docker 部署目录不一致

**坑**：服务器上 Docker 部署目录与预期不符（`/opt/troubleshoot-docker` vs `/data/third_party/monitor-platform`）。

**原因**：历史部署脚本目标路径硬编码为 `/opt/troubleshoot`，用户设计的标准目录是 `/data/third_party/monitor-platform`。

**避免方法**：
- 新建 `deploy/deploy_docker.py` 使用正确路径
- 部署前确认目录结构

---

## 6. 关键文件与命令速查

### 新增文件

| 文件 | 说明 |
|------|------|
| `skill/code/web/services/audit_service.py` | 操作日志查询服务 |
| `skill/code/web/routes/audit.py` | 审计日志路由 |
| `skill/code/web/routes/version.py` | 版本接口 |
| `frontend/src/components/common/AppVersion.vue` | 版本号组件 |
| `frontend/src/views/troubleshoot/Logs.vue` | 问题排查操作日志页 |
| `frontend/src/views/service-monitor/Logs.vue` | 服务监测操作日志页 |
| `frontend/src/views/service-manage/Logs.vue` | 服务管理操作日志页 |
| `deploy/deploy_docker.py` | Docker 部署脚本 |

### 修改文件

| 文件 | 修改内容 |
|------|----------|
| `skill/code/web/server.py` | 注册 audit_bp、version_bp |
| `skill/code/web/routes/troubleshoot.py` | log_audit 补充字段 + SSE 上下文修复 |
| `skill/code/web/routes/auth.py` | log_audit 补充字段 |
| `skill/code/web/routes/submit.py` | log_audit 补充字段 |
| `skill/code/web/routes/export.py` | log_audit 补充字段 |
| `skill/code/web/routes/cache.py` | log_audit 补充字段 |
| `skill/code/web/service_monitor/routes.py` | 新增 log_audit 调用 |
| `frontend/src/router/index.ts` | 新增 3 个日志页路由 |
| `frontend/src/components/layout/AppNavbar.vue` | 集成 AppVersion + logsPath prop |
| `frontend/src/components/layout/AppTopbar.vue` | 集成 AppVersion |
| `frontend/src/layouts/MonitorLayout.vue` | 侧边栏添加操作日志菜单 |
| `frontend/src/layouts/ManageLayout.vue` | 侧边栏添加操作日志菜单 |
| `frontend/src/views/Platform.vue` | 卡片标题改为"运行维护平台" |

### 常用命令

```bash
# 后端单元测试
cd skill/code && python -m pytest -v

# 前端构建
cd frontend && npm run build

# Docker 部署（5.60 服务器）
cd /data/third_party/monitor-platform
sudo docker build -t troubleshoot:latest .
sudo docker run -d --name troubleshoot --restart unless-stopped \
  -p 8088:80 \
  --add-host=host.docker.internal:host-gateway \
  -v /data/third_party/monitor-platform/monitor-data:/app/web/service_monitor/data \
  -v /data/third_party/monitor-platform/data/users.json:/app/web/users.json \
  -v /data/third_party/monitor-platform/data/搜索索引.json:/app/data/搜索索引.json:ro \
  -v /data/third_party/monitor-platform/frontend/dist:/data/dist \
  -v /data/third_party/monitor-platform/logs:/app/web/logs \
  --env-file /data/third_party/monitor-platform/.env \
  troubleshoot:latest

# 验证部署
curl http://localhost:8088/api/health
curl http://localhost:8088/api/version

# 上传前端 dist（增量更新）
SSH_PASSWORD='Ubains@123' python deploy/deploy_docker.py
```

### 服务器信息

- **SSH**：`ubains@192.168.5.60`，密码：`Ubains@123`
- **部署目录**：`/data/third_party/monitor-platform`
- **服务地址**：`http://192.168.5.60:8088`
- **admin 密码**：`Ubains@1357`