# 配置管理后台

项目内置配置后台，用于统一管理登录账号、角色、AI 模型、MCP 和聊天知识库。

> 当前协议版已包含完整前端、知识中心和 Worker。使用说明见 [INTEGRATION_20260916.md](INTEGRATION_20260916.md)，服务端部署见 [deploy/im-admin/README.md](deploy/im-admin/README.md)。完整后台应使用 `python run_backend.py --db backend.db` 启动 API、网关和知识 Worker；单独启动 API 不执行后台知识任务。

## 1. 启动后台

在项目目录运行：

```powershell
python admin_api.py
```

后台监听 `8766`（管理界面 + JSON 接口 + 桌面端同步都在这一个服务上）。端口被占用时会直接报错退出，不再静默顺延——顺延过的端口没人知道，排查时只会看到"连不上"。
桌面端会读取 `backend_runtime.json` 自动发现实际地址，无需手工修改。

> 早期版本还有一个 `8765` 的网页后台（服务端渲染 HTML）。它已整体退役：界面由 Vue 管理端承担，桌面端同步、调用留痕上报也都并进了 `admin_api.py`。`admin_backend.py` 仍在，但只作为数据层被引用，不再自己起服务。

浏览器打开控制台打印的地址。首次创建数据库时使用：

- 用户名：`admin`
- 初始密码：`Admin@123456`

首次登录必须修改密码。也可以在第一次启动前通过环境变量 `WECOM_ADMIN_INITIAL_PASSWORD` 设置不同的初始密码。

数据库默认保存在 `backend.db`，已加入 `.gitignore`。首次建库会读取当前 `ai_settings.json` 作为第一版模型配置。

## 2. 用户与角色

- 管理员（admin）：管理用户、角色并发布模型配置。
- 配置员（operator）：查看和发布模型配置，不能管理用户。
- 只读用户（viewer）：查看后台并登录桌面端同步配置，不能修改配置。

管理员创建的新用户第一次登录网页时也必须修改初始密码，之后才能从桌面端登录。

## 3. 桌面端自动配置

启动 `wechat_gui.py`，进入“AI 人格与能力”页：

1. 点击“登录后台”。
2. 填写后台地址、用户名和密码。
3. 登录成功后，后台配置立即写入本机 `ai_settings.json` 并生效。
4. 桌面端以后会在启动时及每 5 分钟自动同步，也可以点击“立即同步”。

本机只保存 30 天有效的访问令牌，不保存后台密码。登录后台并启用自动同步后，本地 AI 配置字段会变成只读，以后台配置为准；退出后台后可恢复本地编辑。

后台发生端口冲突并自动更换端口时，同一项目目录中的桌面端会自动发现新地址；已有登录令牌可以继续使用。

同一台电脑上启动后台与桌面端时，后台会在 `backend_runtime.json` 发布一个仅限回环地址使用的临时只读同步凭证。桌面软件启动时会先检测该服务并拉取最新配置，所以即使没有保存后台账号登录，也会立即刷新“能力开关”“模型与身份”和“MCP 服务器”中的内容。该凭证不能管理用户或修改后台配置，后台停止后即失效。

## 3.1 智能体（角色与规则）

管理端「AI 模型 → 智能体」决定客服**用什么身份、按什么规矩说话**；模型清单和角色编排决定**用哪个模型**。两件事分开配，因为变更频率差一个数量级——模型半年动一次，话术一周动三次。

一个智能体 = 人设 + 一组规则。规则只有三种：

| 类型 | 触发 | 作用 |
| --- | --- | --- |
| 补充指令（guide） | 关键词留空 = 每轮都注入；填了关键词 = 客户这句话命中才注入 | 追加一句给模型的要求 |
| 禁止措辞（forbid） | **回复里**出现关键词 | 换成这条规则的兜底话术；留空则用客户端内置的那句 |
| 固定口径（reply） | **客户这句话**命中关键词 | 直接发配好的话术，不问模型 |

「启用与协作」里有两种模式：

- **单角色**：只上一个，所谓"切换智能体"就是换这里选的那个。
- **协作**：多个同时在场，客户这句话命中谁的「负责话题」就由谁主答，其余角色的禁止措辞**仍然全体生效**。不论哪种模式，客户看到的始终是同一个人——不会自报角色名，也不会出现"转给同事"。

方案按版本追加，不原地改，回滚就是再存一版指回去。保存后随桌面端配置下发，客户端不用发版。

出厂自带「健康顾问」和「客户经理」两个角色，默认按协作上岗。两个角色都带同一条禁止措辞规则：把客户看得见的文字说成"系统编码/乱码/无法确认具体意思"一律拦下——这是线上真实发生过的事故（客户发来血糖值「13」，模型回"这串像系统编码"）。即使一个智能体都不配，客户端里那条内置兜底也照样生效。

相关权限码：`agent:read` / `agent:write`。升级到这个版本的老后台，管理员自动获得；配置员和只读用户需要在「角色权限」里勾一下。

## 4. 连接已部署的后台

后台所在电脑启动服务：

```powershell
python admin_api.py --host 0.0.0.0 --port 8766
```

桌面端后台地址填写服务器的局域网地址，例如 `http://192.168.1.20:8766`。需要在 Windows 防火墙中仅对可信局域网放行该端口。

Docker、云服务器、HTTPS、备份和升级步骤统一放在 [deploy/im-admin/README.md](deploy/im-admin/README.md)，不再与桌面端使用说明混在一起。

## 5. 管理员密码恢复

停止后台后运行：

```powershell
python admin_api.py --reset-admin-password
```

按提示输入新密码。重置后已有 admin 登录令牌会失效，下次登录仍需再修改一次密码。

## API

- `POST /api/v1/auth/login`：桌面端登录并取得令牌。
- `POST /api/v1/auth/logout`：注销令牌。
- `GET /api/v1/me`：读取当前用户及角色。
- `GET /api/v1/config`：读取当前版本的模型配置。
- `POST /api/v1/model/test`：使用当前提交的模型地址、名称和可选密钥测试连通性（仅管理员和配置员；不会保存配置）。
- `GET /api/v1/desktop/config`：桌面软件启动时只读同步云端配置。
- `GET /health`：健康检查。

模型测试支持三种 `AI_PROVIDER_TYPE`：

- `openai`：OpenAI 兼容接口，向 `chat/completions` 发送最小对话请求。
- `dify`：Dify 应用接口，向 `chat-messages` 发送 blocking 请求。
- `comfyui`：ComfyUI 文生图服务，通过 `GET /system_stats` 检查服务状态。

管理页面可直接选择服务类型并点击“测试模型连通性”。测试使用页面当前值，不保存配置；API Key 留空时沿用后台已保存值，响应和审计记录均不会包含密钥。

## 云端开发模式

管理员或配置员可在“能力开关”中开启“开发模式”并发布。桌面端下次启动或定时同步后，会在“运行日志”显示：

- 云端配置请求的具体地址、配置版本和更新时间；
- 云端返回的具体配置；
- 每次模型调用采用的服务类型、模型名称、基础地址和最终请求地址。

所有诊断均会隐藏 API Key、Token、密码、认证头、Cookie 等敏感值，也不会输出聊天内容。关闭开关并发布后，桌面端下次同步起停止输出这些诊断信息。