kefu/wechat_rpa/BACKEND.md

配置管理后台

项目内置了一个零额外依赖的配置后台，用于统一管理登录账号、角色、AI 模型和 MCP 配置。

如果要把后台部署到另一台电脑、局域网服务器或云服务器，请直接查看独立文档 BACKEND_DEPLOY.md。部署端只需要 admin_backend.py，不需要上传桌面端代码或安装桌面端依赖。

1. 启动后台

在项目目录运行：

python admin_backend.py

后台会优先使用 8765。如果该端口已被其他程序占用，会自动尝试 8766、8767……，并在控制台打印最终地址。桌面端会读取 backend_runtime.json 自动跟随实际端口，无需手工修改。

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

• 用户名：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 服务器”中的内容。该凭证不能管理用户或修改后台配置，后台停止后即失效。

4. 连接已部署的后台

后台所在电脑启动服务：

python admin_backend.py --host 0.0.0.0 --port 8765

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

Docker、云服务器、HTTPS、备份和升级步骤统一放在 BACKEND_DEPLOY.md，不再与桌面端使用说明混在一起。

5. 管理员密码恢复

停止后台后运行：

python admin_backend.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 等敏感值，也不会输出聊天内容。关闭开关并发布后，桌面端下次同步起停止输出这些诊断信息。