startup-plan/工作日志/2026-05-22.md

# 工作日志 — 2026-05-22

---

## 一、Admin 项目架构修复（凌晨）

### 1. admin-ai-chat 模块部署 ✅

**问题：** Admin 前端 `TaskAssistant.tsx` 调用 `/admin-api/ai/chat`，但 NestJS 服务端没有对应模块。

**修复：**
- 提交推送 `admin-ai-chat` 模块（controller/service/module/dto），端点 `POST /admin-api/ai/chat`
- 修复 `AdminUsersModule` 缺少 `PasswordService` 依赖
- 修复 `AdminRole` import 路径 `role.enum` → `admin-role.enum`
- 修复 systemd 启动路径 `dist/main.js` → `dist/src/main.js`
- 创建 admin 账号 `admin@zhixi.app / admin123`
- 添加 `GET /admin-api/ai/dashboard` 端点

### 2. Hermes Agent 集成 🔶

**发现：** 4核4G 上运行 `hermes-agent` Docker 容器（nousresearch/hermes-agent:0.14.0），是一个带 Web Dashboard 的 AI Agent 平台。

**Hermes 架构：**
- Dashboard：端口 9119（Web UI）
- Gateway：负责连接外部平台（飞书/微信/Discord 等 30+ 平台）
- 内置 OpenAI 兼容 API Server（`api_server.py`）：端口 8642，提供 `/v1/chat/completions`

**已完成：**
- ✅ 启动 Hermes Gateway
- ✅ 启用 `api_server` 平台（环境变量 `API_SERVER_ENABLED=true`）
- ✅ 配置 DeepSeek 作为推理后端（`config.yaml`）
- ✅ 设置 API Key 认证 `zhixi-hermes-key-2026`
- ✅ Docker 端口映射 8642
- ✅ UFW 开放 8642（仅内网 172.21.0.0/16 + 10.2.0.0/16）
- ✅ NestJS `AdminAiChatService` 改为 Hermes 优先 + DeepSeek 降级

---

## 二、内网安全组排查与打通 ✅

### 问题
蜂驰云 8核32G（172.21.0.4）→ 轻量云 4核4G（10.2.0.7）:8642 不通

### 排查过程
1. SSH 到两台服务器实测
2. 内网 ping 通（1.8ms）
3. 轻量云 UFW 已放行 172.21.0.0/16 → :8642
4. iptables 里 `YJ-FIREWALL-INPUT` 链（腾讯云 Lighthouse 防火墙）拦截
5. 根因：**控制台防火墙未添加 8642 规则**

### 修复
- 腾讯云控制台 → Lighthouse → 81.70.187.179 → 防火墙 → 添加 TCP 8642，来源 172.21.0.4
- 连通后 curl 测试：http_code=200，延迟 2.84s ✅

---

## 三、去掉 DeepSeek 降级逻辑 ✅

**原因：** Hermes 优先 + DeepSeek 降级的设计导致不知道实际用了哪个服务。

**改动：**
- `admin-ai-chat.service.ts`：移除 `DeepSeekProvider` 注入和 `callDeepSeek` 方法
- `admin-ai-chat.module.ts`：移除 `DeepSeekProvider` 注册
- Hermes 挂了直接抛错，不再静默降级

**全链路架构（最终版）：**
```
Admin 前端 (Vite) → POST /admin-api/ai/chat
  → NestJS AdminAiChatService (8核32G)
    → POST http://10.2.0.7:8642/v1/chat/completions (Hermes)
    → 失败直接报错，前端可见
```

---

## 四、Admin 前端部署 ✅

### 部署配置

| 项目 | 值 |
|------|-----|
| 域名 | `https://admin.longde.cloud` |
| 服务器 | 蜂驰云 8核32G (120.53.227.155) |
| 部署目录 | `/opt/zhixi/admin/dist/` |
| Web 服务器 | Nginx（SPA fallback + 静态资源缓存） |
| SSL | Let's Encrypt，2026-08-20 到期，自动续期 |

### Nginx 配置
- `/` → SPA fallback `try_files $uri /index.html`
- `/assets/` → 1年缓存
- HTTP → HTTPS 自动跳转

### CI/CD 流水线
```
push main → prod runner
  → git clone http://10.2.0.7:3000/wangdl/admin-projects.git
  → npm ci → npm run build
  → rsync dist/ → /opt/zhixi/admin/dist/
  → nginx reload
  → curl 健康检查
```

---

## 五、修复 API 部署流水线 ✅

### 发现的问题
旧 workflow 只部署了 RAG Worker，**NestJS 代码不会自动更新**！

### 旧流水线（有缺陷）
| 步骤 | 状态 |
|------|------|
| git clone/pull | ✅ |
| npm ci | ❌ 缺失 |
| prisma generate | ❌ 缺失 |
| nest build | ❌ 缺失 |
| prisma migrate deploy | ❌ 缺失 |
| rsync dist/node_modules/prisma | ❌ 缺失 |
| restart zhixi-api | ❌ 缺失 |
| deploy RAG Worker | ✅ |
| health check | ✅ |

### 新流水线
```
push main → prod runner
  → git clone/pull
  → npm ci
  → prisma generate + nest build
  → docker start mysql/redis/qdrant
  → 清理失败 migration
  → prisma migrate deploy
  → rsync dist/ node_modules/ prisma/ package.json → /opt/zhixi/backend/
  → systemctl restart zhixi-api
  → deploy RAG Worker + restart zhixi-worker
  → curl health check
```

### 踩坑
- `prisma migrate deploy` 报错 exit code 1 → 缺少 `DATABASE_URL` 环境变量，workflow 顶部加 `env` 解决

---

## 六、Hermes api_server 架构确认

### Gateway 配置
```
/opt/data/.env:
  API_SERVER_ENABLED=true
  API_SERVER_KEY=zhixi-hermes-key-2026
  API_SERVER_HOST=0.0.0.0
  API_SERVER_PORT=8642

/opt/data/config.yaml:
  model: deepseek-v4-flash
  provider: custom
  base_url: https://api.deepseek.com/v1
  api_key: sk-ddddea4986d843be978ced9e82988fa0
```

### gateway_state.json
```json
{
  "pid": 91,
  "gateway_state": "running",
  "platforms": {
    "api_server": {
      "state": "connected",
      "updated_at": "2026-05-21T16:26:56Z"
    }
  }
}
```

### api_server.py 端点
- `POST /v1/chat/completions` — OpenAI Chat 格式
- `POST /v1/responses` — OpenAI Responses 格式
- `GET /v1/models` — 模型列表
- `GET /v1/capabilities` — API 能力声明
- `POST /v1/runs` — 启动 run（异步）
- `GET /health` — 健康检查

---

## 七、服务器状态（最终）

### 8核32G (120.53.227.155)

| 服务 | 状态 |
|------|------|
| zhixi-api | ✅ active，支持自动部署 |
| zhixi-worker | ✅ active，支持自动部署 |
| gitea-runner (prod) | ✅ active |
| MySQL/Redis/Qdrant | ✅ 运行中 |
| admin.longde.cloud | ✅ HTTPS，自动部署 |
| api.longde.cloud | ✅ HTTPS |

### 4核4G (81.70.187.179)

| 服务 | 状态 |
|------|------|
| hermes-agent | ✅ Dashboard :9119，API :8642 |
| Gitea 1.23.8 | ✅ |
| Nginx | ✅ |
| gitea-runner (web) | ✅ |
| UFW | ✅ 22/80/443/2222/9119/8642 |

### 部署流水线对比

| | api-server | admin-projects |
|------|------|------|
| 仓库 | suche-Hermes/api-server | wangdl/admin-projects |
| Runner | prod | prod |
| 构建 | npm ci → nest build | npm ci → vite build |
| 部署 | rsync → systemctl restart | rsync → nginx reload |
| 域名 | api.longde.cloud | admin.longde.cloud |

---

## 八、当前待办

### 已完成
1. ~~admin-ai-chat 模块部署~~ ✅
2. ~~AdminUsersModule PasswordService 依赖修复~~ ✅
3. ~~AdminRole import 路径修复~~ ✅
4. ~~systemd dist 路径修复~~ ✅
5. ~~Admin 账号创建~~ ✅
6. ~~Hermes Gateway 启动~~ ✅
7. ~~Hermes api_server 平台启用~~ ✅
8. ~~NestJS → Hermes 优先调用~~ ✅
9. ~~腾讯云安全组添加 8642 端口~~ ✅
10. ~~去掉 DeepSeek 降级逻辑~~ ✅
11. ~~Admin 前端部署 + HTTPS~~ ✅
12. ~~API 部署流水线修复~~ ✅

### 待完成
13. ⏳ 4核4G Nginx 代理 `/hermes-api/` → `127.0.0.1:8642`
14. 🟢 AI 提取 prompt 调优（待真实文档）
15. 🟢 COS 备份同步 + 生命周期清理
16. 🟢 MySQL 物理清理脚本
17. 🟢 Docker Compose 统一
18. 🟢 logrotate 确认
19. 🔴 学习引擎串联（待产品决策 → `待决策事项.md`）
20. ⬜ 阶段九：iOS API 对接 + 用户闭环测试
21. ⬜ 阶段十：后台管理 + 额度检查