docs: 更新 HANDOFF - SSH sudo 自动检测完成

记录 SSH sudo 自动检测功能实现过程和踩坑 Co-Authored-By: Claude <noreply@anthropic.com>

docs: 更新 HANDOFF - SSH sudo 自动检测完成
记录 SSH sudo 自动检测功能实现过程和踩坑 Co-Authored-By: Claude <noreply@anthropic.com>
437a1b7e · 陈泽健 · 65b25c4d · 437a1b7e
--- a/HANDOFF.md
+++ b/HANDOFF.md
-# HANDOFF — 离线模式双界面 + 文档上传管理
+# HANDOFF — SSH sudo 自动检测 + Docker 权限适配

-> 最后更新：2026-08-03 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：czj
+> 最后更新：2026-08-05 ｜ 分支：troubleshoot-ai-assistant ｜ 负责人：czj

 ---

 ## 1. 我们在做什么

-### 1.1 问题排查双模式界面升级
+**背景**：用户在 9.89 服务器上执行巡检时，发现 Docker 容器显示为"未运行"，但实际容器在运行。根本原因是 SSH 用户 `openkylin` 不在 docker 组，需要 `sudo docker` 才能执行 docker 命令，而巡检脚本直接执行 `docker ps` 导致权限拒绝。

-在已有在线 AI 分析模式基础上，升级离线模式（`OFFLINE_MODE=true`）为全新产品树界面：
+**目标**：实现 SSH sudo 自动检测和提权，让巡检脚本在非 root 用户下也能正确检测 Docker 容器。

- **在线模式**（`OFFLINE_MODE=false`）：保持原有 AI 分析界面不变
- **离线模式**（`OFFLINE_MODE=true`）：左侧产品树 + 右侧资料下载/常见问题面板
+**来源**：用户反馈巡检报告显示容器未运行，9.89 上实际有 12 个容器在运行。

-前端入口 `Index.vue` 根据 `/api/health` 的 `offline_mode` 自动切换两套界面。
+---

-### 1.2 管理员文档上传/删除功能
+## 2. 已经完成了什么

-因 Windows ACL 权限问题导致本地维护手册文件无法通过 git/tools 上传到服务器，在页面上增加了管理员专属的上传/删除文档功能，通过浏览器直接上传到服务器。
+### 2.1 SSHExecutor sudo 自动检测 ✅

---
+修改 `skill/code/web/service_monitor/utils/executor.py`：
+- `_detect_sudo_need()` 方法连接后自动检测：
+  1. 先测试 `docker ps` 是否可直接执行
+  2. 失败则测试 `sudo -n docker ps`
+  3. 尝试用 SSH 密码自动配置免密 sudoers
+  4. 配置失败时给出明确提示
+- `_exec()` 方法根据 `use_sudo` 自动用 `sudo bash -c` 包裹命令
+- `_try_configure_passwordless_sudo()` 尝试自动写入 `/etc/sudoers.d/<username>`

-## 2. 已经完成了什么
+### 2.2 Docker 检测脚本 sudo 适配 ✅

-### 2.1 后端产品 API ✅
+修改 `skill/code/web/service_monitor/assets/service/20_docker_basic.sh`：
+- 新增 `_detect_docker_sudo()` 函数，自动检测 `docker` 或 `sudo docker`
+- 所有 docker 命令使用 `$DOCKER_CMD` 变量
+- 每个检测函数开头增加 `if [ -z "$DOCKER_CMD" ]` 保护

-| 子任务 | 说明 | 验证 |
-|--------|------|------|
-| `products.json` | 9 个产品配置（门口屏/无纸化/智屏集控/蓝牙基站/双屏互动/会议助手/语音助手/IDEATOP-安卓/IDEATOP-中控），28 份文档映射 | `curl /api/troubleshoot/products` 返回正确 |
-| `product_service.py` | 产品服务模块：get_products/get_product/get_documents/get_document_path/add_document/delete_document | Python 模块加载正常 |
-| `search_engine.py` | 新增 `search_by_product()` 方法（按 apk_product + tags 筛选知识库记录） | 单元测试全绿 |
-| API 端点 | `/api/troubleshoot/products`、`/products/{id}`、`/products/{id}/documents`、`/documents/{id}/download`、`/documents/upload`、`/documents/{id}/delete`、`/products/{id}/faqs` | 全链路 HTTP 验证通过 |
+### 2.3 前端目标管理增强 ✅

-### 2.2 前端双模式界面 ✅
+修改 `skill/code/web/templates/service_monitor/targets.html`：
+- 添加"需要 sudo 提权"复选框
+- 目标列表显示 sudo 状态列
+- 编辑功能完整实现：`openEdit()` 通过 API 回填数据

-| 子任务 | 文件 | 说明 |
-|--------|------|------|
-| 模式切换入口 | `frontend/src/views/troubleshoot/Index.vue` | 调用 `/api/health` 判断模式，动态加载 OnlineIndex 或 OfflineIndex |
-| 在线模式 | `frontend/src/views/troubleshoot/OnlineIndex.vue` | 原 Index.vue 内容，AI 分析界面保持不变 |
-| 离线模式主布局 | `frontend/src/views/troubleshoot/OfflineIndex.vue` | 左右分栏：左侧产品树 + 右侧内容区 |
-| 产品树组件 | `frontend/src/components/troubleshoot/ProductTree.vue` | 搜索框 + 展开折叠 + 产品资料/常见问题子菜单 |
-| 产品资料面板 | `frontend/src/components/troubleshoot/DocumentsPanel.vue` | 文档列表 + 下载 + **上传/删除（管理员）** |
-| 常见问题面板 | `frontend/src/components/troubleshoot/FAQsPanel.vue` | 已置空，显示「常见问题整理中」 |
-| API 封装 | `frontend/src/api/troubleshoot.ts` | 新增 getProducts/getProduct/getProductDocuments/downloadDocument/uploadDocument/deleteDocument |
-| 类型定义 | `frontend/src/types/troubleshoot.ts` | 新增 Product/ProductDocument/FAQ 等类型 |
-
-### 2.3 文档上传/删除功能 ✅
-
-| 功能 | API | 验证 |
-|------|-----|------|
-| 上传 | `POST /api/troubleshoot/documents/upload` (multipart/form-data) | curl 测试上传 4395 bytes → 下载成功 |
-| 删除 | `DELETE /api/troubleshoot/documents/{id}/delete` | curl 测试删除成功 |
-| 权限 | 仅 admin 可上传/删除 | 非 admin 返回 403 |
-
-### 2.4 部署 ✅
-
-| 子任务 | 说明 |
-|--------|------|
-| 后端代码 | `product_service.py`、`routes/troubleshoot.py` 已部署到 5.60 容器内 |
-| 前端构建 | `npm run build` 产物已部署到 5.60 前端目录 |
-| Nginx | 已配置 `client_max_body_size 100m` 支持大文件上传 |
-| 容器重启 | 已重启，服务正常运行 |
+### 2.4 后端数据支持 ✅
+
+修改 `skill/code/web/service_monitor/services/target_service.py`：
+- `create_target()` / `update_target()` 支持 `use_sudo` 字段
+- `list_targets()` / `_build_view()` 返回 `use_sudo` 状态
+
+修改 `skill/code/web/service_monitor/routes.py`：
+- 新增 `GET /api/service-monitor/targets/<target_id>` API（编辑回填用）
+
+### 2.5 部署到 5.60 ✅
+
+- 重建 Docker 镜像（包含最新 sudo 自动检测代码）
+- 修复端口冲突（systemd 与 Docker 容器抢占 8088，已禁用 systemd）
+- 修复前端文件缺失（`/opt/troubleshoot/dist/` 为空，已恢复）
+- 修复搜索索引文件错误（目录→文件，volume 挂载覆盖）
+- 修复通知配置解密失败（`notifications.json` 中旧密文无法解密，已清除）
+
+### 2.6 代码提交 ✅
+
+提交 `65b25c4d` 到 `troubleshoot-ai-assistant` 分支，已推送到远程。

 ---

 ## 3. 当前卡在哪

-**卡点：`Docs/维护手册/` 下的 28 个 docx/pdf 文件因 Windows ACL 权限拒绝访问，无法通过 git、Python、PowerShell 等任何方式读取或上传。**
-
- 错误：所有文件读取操作返回 `PermissionError: [Errno 13] Permission denied`
- 影响：服务器上的对应文件全部为 0 字节空文件
- 根本原因：文件 ACL 中存在 Deny 规则（`S-1-22-1-1106 Deny Modify`）
+**无卡点**。所有功能已完成并部署验证。

-**解决方案**：已实现页面上传功能，管理员可通过浏览器直接上传文件到对应产品目录。用户可通过此功能重新上传那 28 份文档。
+5.60 服务状态：
+- 健康检查：✅ ok
+- 前端页面：✅ `http://192.168.5.60:8088/`
+- 通知 API：✅ 已修复（需重新配置钉钉/邮箱凭据）
+- 搜索引擎：✅ TF-IDF 模式
+- 定时任务：✅ 2 个任务运行中

 ---

@@ -80,117 +81,151 @@

 | 优先级 | 任务 | 说明 |
 |--------|------|------|
-| **P1** | 通过页面上传 28 份维护手册文档 | 用 admin 账号登录，在产品资料面板中逐产品上传文件 |
-| **P2** | 提供常见问题（排查指引）内容 | 用户整理各产品常见问题的排查步骤后，解除 FAQsPanel 的空状态 |
-| **P3** | 清理 deploy/ 下的临时脚本 | 删除本次调试产生的 upload_docs_v*.py、encode_docs.ps1 等临时文件 |
-| **P4** | 提交未提交的代码变更 | `git status` 显示还有前端组件和后端 service 的修改待提交 |
-| **P5** | 启用 product_service.py 的 faq 加载逻辑 | 移除 `loadData()` 中的 `return` 占位语句 |
+| **P1** | 验证 9.89 巡检 | 在目标管理添加 9.89（主机：192.168.9.89，用户：openkylin），运行全量巡检，验证 Docker 容器检测是否正常显示 12 个容器 |
+| **P2** | 验证定时任务 | 明天 08:30/09:00 检查定时任务是否自动执行，巡检报告是否生成 |
+| **P3** | 重新配置通知凭据 | 进入通知配置页面重新填写钉钉 secret（容器重建后加密密钥变更，旧密文无法解密） |
+| **P4** | 为 `MONITOR_ENC_KEY` 设置固定值 | 在 `docker-compose.yml` 的 environment 中设置固定的加密密钥，避免每次重建容器后密钥变更导致凭据解密失败 |

 ---

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

-### 坑 1：Windows 中文路径文件 ACL 拒绝访问
+### 坑 1：Docker 容器与 systemd 服务端口冲突
+
+**坑**：Docker 容器和 systemd 服务同时运行抢占 8088 端口，systemd 每 6 秒重启一次，累计重启 9300+ 次。定时任务因服务不稳定无法执行。
+
+**原因**：部署脚本只更新宿主机文件并重启 systemd 服务，没检查 Docker 容器是否已在运行。容器先启动占了端口，systemd 后启动失败。
+
+**避免方法**：
+```bash
+# 部署前先检查
+sudo docker ps | grep troubleshoot  # 如果有容器在运行
+sudo systemctl disable troubleshoot  # 禁用 systemd，避免冲突
+# 代码更新必须重建镜像
+cd /data/third_party/monitor-platform && sudo docker compose up -d --build
+```
+
+### 坑 2：Docker 镜像内代码未随部署更新

-**坑**：`Docs/维护手册/` 下的所有 docx/pdf 文件，Python（`open()`、`pathlib.read_bytes()`、`os.open()`）、Git（`git add`）、PowerShell（`Copy-Item`）、SFTP 均返回 `Permission denied`。
+**坑**：部署脚本只更新宿主机 `/opt/troubleshoot/web/` 下的文件，但 Docker 镜像构建时 `COPY skill/code/web/ /app/web/` 复制代码，容器内代码仍是旧版本。sudo 自动检测功能部署后不生效。

-**原因**：文件 ACL 中存在 Deny 规则 `S-1-22-1-1106 Deny DeleteSubdirectoriesAndFiles, Modify, ChangePermissions, TakeOwnership`。可能是文件从其他路径复制时带入的权限，或 OneDrive/杀毒软件锁定。
+**原因**：代码文件不在 volume 挂载范围内（只有 data/dist/logs 通过 volume 挂载），必须重建镜像才能更新容器内代码。

 **避免方法**：
-1. 上传附件前先检查文件属性 → 安全 → 确认当前用户有读取权限
-2. 如果文件被锁定，先复制到新文件夹（会重置 ACL），再操作
-3. **终极方案**：通过浏览器上传，完全绕过本地文件系统权限
+```bash
+# 代码更新后必须重建镜像
+sudo rsync -av --delete /opt/troubleshoot/web/ /data/third_party/monitor-platform/skill/code/web/
+cd /data/third_party/monitor-platform && sudo docker compose up -d --build
+```

-### 坑 2：Git Bash 中 `$_` 变量被展开
+### 坑 3：volume 挂载文件类型不匹配导致容器启动失败

-**坑**：在 Git Bash 内联运行 PowerShell 命令时，`$_`、`$files` 等 PowerShell 变量被 Bash 解析为环境变量展开。
+**坑**：`搜索索引.json` 被误创建为目录，docker-compose 挂载时报错 `not a directory: Are you trying to mount a directory onto a file`，容器无法启动。

-**避免方法**：始终将 PowerShell 脚本放在 `.ps1` 文件中执行，不要内联在 Bash 命令行中。
+**原因**：`docker compose down -v` 删除 volumes 后重建时，宿主机上 `/opt/troubleshoot/data/搜索索引.json` 被错误创建为目录。docker-compose 试图将目录挂载到镜像内的文件位置，类型不匹配。

-### 坑 3：SFTP `sftp.file(path, 'wb')` 写入中文路径文件为 0 字节
+**避免方法**：
+```bash
+# 重建前检查挂载文件类型
+sudo file /opt/troubleshoot/data/搜索索引.json  # 应输出：JSON text data
+# 如果是目录，先删除再复制正确的文件
+sudo rm -rf /opt/troubleshoot/data/搜索索引.json
+sudo cp /data/third_party/monitor-platform/data/搜索索引.json /opt/troubleshoot/data/
+# 必须先停止容器再修改挂载文件
+sudo docker stop troubleshoot
+```

-**坑**：SFTP 的 `sftp.file()` 对含中文路径的文件写入后，`stat()` 确认写入成功但实际文件大小为 0。
+### 坑 4：通知配置解密失败导致 API 500

-**原因**：paramiko SFTP 客户端编码问题，中文路径在创建文件时成功（0 字节），但写入操作静默失败。
+**坑**：`notifications.json` 中钉钉 secret 用旧密钥加密（`enc:gAAAAA...`），重建容器后 `MONITOR_ENC_KEY` 变更，解密失败导致通知 API 返回 500。

-**避免方法**：使用 `sftp.putfo(io.BytesIO(data), path)` 替代 `sftp.file()` 进行上传。
+**原因**：Fernet 加密密钥每次容器启动可能不同（如果 `MONITOR_ENC_KEY` 环境变量未固定），旧密文无法解密。

-### 坑 4：`docker cp` 中文路径复制也为 0 字节
+**避免方法**：在 `docker-compose.yml` 中设置固定的 `MONITOR_ENC_KEY` 环境变量。已清除无法解密的加密字段作为临时修复。

-**坑**：`sudo docker cp /data/.../门口屏/01-文档.docx troubleshoot:/app/...` 同样产生 0 字节文件。
+### 坑 5：sudo 检测逻辑不完整——只测用户权限没测命令权限

-**原因**：Docker cp 对中文路径文件也有编码问题。
+**坑**：最初只检测 `sudo -n whoami`（用户是否有免密 sudo），没检测 Docker 命令权限。9.89 上 openkylin 有免密 sudo 但不在 docker 组，`docker ps` 仍失败。

-**避免方法**：使用 `tar cf - ... | docker exec -i ... tar xf -` 管道方式。
+**原因**：想当然认为"有 sudo 权限就能执行所有命令"，忽略了 docker 组权限。

-### 坑 5：`echo "{base64}" | base64 -d` 对大文件失败
+**避免方法**：检测要具体到命令本身。正确逻辑：先测 `docker ps`，失败再测 `sudo -n docker ps`，而不是只测 `sudo -n whoami`。

-**坑**：将 base64 编码的文件内容通过 `echo` 管道给 `base64 -d`，对大文件（>10MB）会截断。
+### 坑 6：前端 dist 目录被空 volume 覆盖

-**原因**：shell 命令行参数长度限制 + echo 对大字符串处理有问题。
+**坑**：docker-compose 将 `/opt/troubleshoot/dist` 挂载到容器的 `/data/dist`，但 `/opt/troubleshoot/dist` 是空目录，覆盖了镜像内构建时复制的前端文件，导致首页 403。

-**避免方法**：先把 base64 内容写入临时文件，再 `base64 -d file.b64 > output`。
+**原因**：`docker compose down -v` 删除旧 volume 后，新建的 volume 目录为空。
+
+**避免方法**：重建后必须将前端文件复制到挂载目录：
+```bash
+sudo cp -r /data/third_party/monitor-platform/frontend/dist/* /opt/troubleshoot/dist/
+```

 ---

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

-### 本次新增/修改文件
+### 本次修改的核心文件

-| 文件 | 说明 |
+| 文件 | 改动 |
 |------|------|
-| `skill/code/web/products.json` | 产品配置文件（9 产品 / 28 文档映射） |
-| `skill/code/web/services/product_service.py` | 产品服务模块（含上传/删除方法） |
-| `skill/code/web/routes/troubleshoot.py` | 新增 upload/delete API + 产品 API |
-| `skill/code/web/search_engine.py` | 新增 `search_by_product()` |
-| `frontend/src/views/troubleshoot/Index.vue` | 模式切换入口 |
-| `frontend/src/views/troubleshoot/OnlineIndex.vue` | 在线模式界面（原内容） |
-| `frontend/src/views/troubleshoot/OfflineIndex.vue` | 离线模式主布局 |
-| `frontend/src/components/troubleshoot/ProductTree.vue` | 产品树组件 |
-| `frontend/src/components/troubleshoot/DocumentsPanel.vue` | 产品资料面板（含上传/删除） |
-| `frontend/src/components/troubleshoot/FAQsPanel.vue` | 常见问题面板（已置空） |
-| `frontend/src/types/troubleshoot.ts` | 新增离线模式类型 |
-| `frontend/src/api/troubleshoot.ts` | 新增产品/上传/删除 API |
-| `frontend/src/router/index.ts` | /troubleshoot 路由统一入口 |
-| `nginx/nginx.conf` | 新增 `client_max_body_size 100m` |
-| `Dockerfile` | 新增维护手册目录 COPY |
-| `deploy/deploy_docker.py` | 新增维护手册目录上传路径 |
-
-### 常用命令
+| `skill/code/web/service_monitor/utils/executor.py` | SSHExecutor sudo 自动检测（+150 行） |
+| `skill/code/web/service_monitor/services/target_service.py` | use_sudo 字段支持（+10 行） |
+| `skill/code/web/service_monitor/routes.py` | 新增 GET 单个目标 API（+12 行） |
+| `skill/code/web/service_monitor/assets/service/20_docker_basic.sh` | Docker 检测 sudo 适配（+69 行） |
+| `skill/code/web/templates/service_monitor/targets.html` | 前端 sudo 选项 + 编辑回填（+37 行） |
+
+### 部署命令

 ```bash
-# 前端构建
-cd frontend && npm run build
+# 同步代码到构建目录
+sudo rsync -av --delete /opt/troubleshoot/web/ /data/third_party/monitor-platform/skill/code/web/
+
+# 重建并启动容器
+cd /data/third_party/monitor-platform && sudo docker compose up -d --build

-# 后端单元测试（218 用例）
-cd skill/code && python -m pytest -v
+# 恢复前端文件
+sudo cp -r /data/third_party/monitor-platform/frontend/dist/* /opt/troubleshoot/dist/

-# 部署前端到 5.60
-python deploy/deploy_frontend.py
+# 健康检查
+curl http://localhost:8088/api/health
+```

-# 部署后端代码到 5.60
-python deploy/upload_backend.py
+### 调试命令

-# 验证服务
-curl http://192.168.5.60:8088/api/health
-curl http://192.168.5.60:8088/api/troubleshoot/products
+```bash
+# 测试 SSH sudo（9.89）
+ssh openkylin@192.168.9.89 "whoami && sudo -n whoami && docker ps 2>&1 | head -3 && sudo docker ps 2>&1 | head -3"
+
+# 容器内测试通知服务
+sudo docker exec troubleshoot python3 << 'EOF'
+import sys; sys.path.insert(0, '/app/web')
+from service_monitor.services import notification_service
+import json; print(json.dumps(notification_service.get_config_masked(), ensure_ascii=False, indent=2)[:300])
+EOF
+
+# 查看容器日志
+sudo docker logs troubleshoot --tail 50
+
+# 检查容器内文件
+sudo docker exec troubleshoot ls -la /app/data/
+sudo docker exec troubleshoot ls -la /app/web/service_monitor/data/
+```

-# 测试上传（需 admin session）
-curl -c /tmp/c.txt -X POST http://192.168.5.60:8088/login \
-  -H 'Content-Type: application/json' \
-  -d '{"username":"admin","password":"Ubains@1357"}'
-curl -b /tmp/c.txt -X POST http://192.168.5.60:8088/api/troubleshoot/documents/upload \
-  -F "file=@test.pdf" -F "product_id=door-screen"
+### 环境配置

-# 产品与文档目录映射
-# 服务器：/data/third_party/monitor-platform/Docs/维护手册/{产品名}/{文件名}
-# 容器内：/app/Docs/维护手册/{产品名}/{文件名}
+```bash
+# docker-compose.yml 关键环境变量
+LOCAL_SSH_USER=ubains
+LOCAL_SSH_PASSWORD=Ubains@123
+MONITOR_ENC_KEY=  # 建议设为固定值，避免重建后凭据解密失败
 ```

-### 服务器信息
+### 登录凭据

- **SSH**：`ubains@192.168.5.60`，密码：`Ubains@123`
- **部署目录**：`/data/third_party/monitor-platform`
- **服务地址**：`http://192.168.5.60:8088`
- **admin 密码**：`Ubains@1357`
- **离线模式**：`OFFLINE_MODE=true`（`.env` 配置）
+| 服务 | 地址 | 用户名 | 密码 |
+|------|------|--------|------|
+| Web 管理员 | http://192.168.5.60:8088 | admin | Ubains@1357 |
+| 5.60 SSH | 192.168.5.60 | ubains | Ubains@123 |
+| 9.89 SSH | 192.168.9.89 | openkylin | Ubains@123 |