完善开源交付文档与Docker部署安全配置

2026-05-07 12:36:16 +08:00
parent 8579b7ec27
commit 4515b605b9
9 changed files with 434 additions and 126 deletions
--- a/README.MD
+++ b/README.MD
@@ -1,28 +1,31 @@
 # ABOT

-ABOT 是一个基于插件体系构建的微信机器人项目，包含消息处理主链路、管理后台、MySQL/Redis 存储、定时任务与多类 AI / 内容插件能力。当前仓库更适合有一定 Python 与部署基础的维护者进行二次开发、私有部署与功能扩展。
+ABOT 是一个面向长期维护的微信机器人项目，包含消息接入、插件体系、管理后台、MySQL / Redis 存储、定时任务以及 AI 扩展能力。  
+当前仓库已经完成一轮面向开源发布的工程整理，适合用于二次开发、私有部署和多版本 `wechat_ipad server` 接入演进。

-## 项目定位
+## 项目特点

- 面向“可持续迭代的机器人平台”，不是一次性脚本
- 核心能力包括消息接入、插件化处理、后台管理、数据归档与 AI 扩展
- 当前默认假设你具备 MySQL、Redis、Docker、环境变量配置的基础经验
+- 插件化机器人主链路，便于按业务拆分能力
+- 自带 Dashboard 管理后台，支持状态查看、插件管理、消息与联系人相关页面
+- 支持 `legacy_855` 与 `server_864` 两类 `wechat_ipad server` 适配入口
+- 配置统一走 `.env + config.yaml`，登录态运行时状态落到 provider 独立目录
+- 提供 Docker / Docker Compose 基础部署骨架，便于快速上线验证

-## 当前主要能力
+## 当前能力范围

- 微信消息接入与机器人主循环
- 插件加载、启停、热更新与后台管理
- MySQL + Redis 双存储
- AI 自动回复、消息总结、成员画像等能力
- 签到、积分、排行榜、内容推送、媒体处理等业务插件
+- 微信消息接入与实时处理
+- 插件加载、启停、热更新治理
+- MySQL + Redis 数据存储
+- 联系人、群信息、消息归档、统计与部分运营分析页面
+- AI 自动回复、消息总结、成员画像、内容推送等扩展能力

 ## 快速开始

 ### 方式一：Docker Compose

-适合第一次快速跑通部署骨架。
+适合第一次快速跑通完整部署骨架。

-1. 复制 Docker 环境变量示例
+1. 复制 Docker 环境变量模板

 ```bash
 cp .env.docker.example .env
@@ -34,7 +37,16 @@ Windows PowerShell：
 Copy-Item .env.docker.example .env
 ```

-2. 按实际环境修改 `.env` 中的数据库密码、`WECHAT_SERVER_URL`、`WECHAT_SERVER_TYPE` 等参数
+2. 至少修改以下变量
+
+- `ABOT_DB_PASSWORD`
+- `WECHAT_SERVER_URL`
+- `WECHAT_SERVER_IP`
+- `WECHAT_SERVER_PORT`
+- `WECHAT_SERVER_TYPE`
+- `WECHAT_SERVER_KEY`：仅 `server_864` 必填
+- `ABOT_DASHBOARD_PASSWORD`
+- `ABOT_DASHBOARD_SECRET_KEY`

 3. 启动服务

@@ -42,13 +54,19 @@ Copy-Item .env.docker.example .env
 docker compose up -d --build
 ```

-更多说明见 [docs/Docker部署说明.md](/d:/learn/abot/docs/Docker部署说明.md:1)。
+4. 访问 Dashboard
+
+- 默认地址：`http://127.0.0.1:8888`
+- 默认用户名：`admin`
+- 默认密码以你的 `.env` 中 `ABOT_DASHBOARD_PASSWORD` 为准
+
+更完整的上线说明见 [docs/Docker部署说明.md](/d:/learn/abot/docs/Docker部署说明.md:1)。

 ### 方式二：本地直跑

 1. 准备 Python 3.10+
 2. 准备 MySQL、Redis
-3. 复制配置文件
+3. 复制配置模板

 ```bash
 cp config.example.yaml config.yaml
@@ -71,40 +89,57 @@ pip install -r requirements.txt
 pip install pysilk-mod
 ```

-5. 启动主程序
+5. 启动项目

 ```bash
 python main.py
 ```

-## 配置说明
+## 配置约定

-### 全局配置
+### 静态配置

-项目支持从 `.env` 自动加载环境变量，并在 [config.example.yaml](/d:/learn/abot/config.example.yaml:1) / `config.yaml` 中使用：
+推荐只维护以下两类文件：

- `${ENV_NAME}`
- `${ENV_NAME:默认值}`
+- `.env`
+- `config.yaml`

-示例：
-
- `${ABOT_DB_PASSWORD}`：必须提供
- `${ABOT_DB_HOST:127.0.0.1}`：可缺省时回退
+`config.yaml` 支持 `${ENV_NAME}` / `${ENV_NAME:default}` 占位符，因此更推荐把敏感配置写进 `.env`，把结构与默认值保留在 YAML 模板里。

 ### wechat_ipad 配置

-现在 `wechat_ipad` 的静态连接参数已经统一走 `.env` / `config.yaml`：
+当前 `wechat_ipad` 的静态连接配置统一走环境变量：

 - `WECHAT_SERVER_URL`
 - `WECHAT_SERVER_IP`
 - `WECHAT_SERVER_PORT`
 - `WECHAT_SERVER_TYPE`
+- `WECHAT_SERVER_KEY`：仅 `server_864` 必填

-登录后的 `wxid / device_id / device_name` 不再要求你手工维护，它们会自动写入本地状态文件：
+运行时状态不再要求人工维护，会自动写到：

- 默认路径：`wechat_ipad/providers/<server_type>/runtime_state.toml`
- 可通过 `WECHAT_STATE_FILE` 覆盖
- 启动时会自动兼容历史 `wechat_ipad/config.toml` 中已有的登录态
+- `wechat_ipad/providers/<server_type>/runtime_state.toml`
+
+这意味着：
+
+- 每个 provider 的登录态彼此隔离
+- 切换 `855 / 864` 不会默认串用同一份状态
+- 开源仓库不需要再长期维护多份分散配置文件
+
+## Docker 交付说明
+
+当前仓库已经提供以下开源友好交付物：
+
+- [Dockerfile](/d:/learn/abot/Dockerfile:1)
+- [docker-compose.yml](/d:/learn/abot/docker-compose.yml:1)
+- [docker-entrypoint.sh](/d:/learn/abot/docker-entrypoint.sh:1)
+- [.env.docker.example](/d:/learn/abot/.env.docker.example:1)
+
+容器化方案的边界是：
+
+- `abot`、`mariadb`、`redis` 已拆成独立服务
+- `wechat_ipad server` 仍建议跑在宿主机或独立机器
+- Dashboard 账号、密码、Session Secret、Webhook Token 都支持环境变量覆盖

 ## 目录结构

@@ -112,11 +147,11 @@ python main.py
 abot/
 ├── admin/                # 管理后台
 ├── base/                 # 插件基础接口与管理能力
-├── db/                   # 数据库访问层与迁移脚本
-├── docs/                 # 部署、设计、使用文档
+├── db/                   # 数据库访问层与 SQL 脚本
+├── docs/                 # 部署、设计与路线图文档
 ├── plugins/              # 业务插件
 ├── utils/                # 通用工具与服务
-├── wechat_ipad/          # 微信相关客户端与 server 对接代码
+├── wechat_ipad/          # 微信接入与 provider 适配层
 ├── Dockerfile
 ├── docker-compose.yml
 ├── config.example.yaml
@@ -124,64 +159,68 @@ abot/
 └── main.py
 ```

-## 管理后台
+## Dashboard 与默认安全项

- 默认端口：`8888`
- 配置文件：[`admin/dashboard/config.toml`](/d:/learn/abot/admin/dashboard/config.toml:1)
- 公开仓库中的账号密码与 webhook token 已改为占位值，部署前务必自行修改
+Dashboard 默认配置文件位于 [admin/dashboard/config.toml](/d:/learn/abot/admin/dashboard/config.toml:1)。

-## Docker 化现状
+为了适配公开仓库，这一层已经做了两件事：

-本仓库现在提供的是“开源友好”的基础部署骨架：
+- 仓库中的默认密码已不再使用弱口令 `admin123`
+- Docker / 环境变量可以直接覆盖后台账号、密码和 webhook token

- 应用、MariaDB、Redis 已拆分为独立服务
- 提供 `docker-compose.yml`、`.dockerignore`、`.env.docker.example`
- 静态连接配置统一通过 `.env` 注入，更适合开源仓库和多环境部署
- wechat 登录态缓存默认落到对应 provider 目录下
+正式部署前仍建议你明确设置：

-当前仍建议你在正式生产前继续补充：
+- `ABOT_DASHBOARD_USERNAME`
+- `ABOT_DASHBOARD_PASSWORD`
+- `ABOT_DASHBOARD_SECRET_KEY`
+- `ABOT_TRENDRADAR_WEBHOOK_TOKEN`

- HTTPS / 反向代理
- 备份策略
- CI/CD
- 监控与告警
+## License 与开源边界

-## 开源说明
+### 主许可证

-### License 要不要改
+当前仓库主代码采用 [MIT License](/d:/learn/abot/LICENSE:1)。

-当前主代码仍按 MIT License 分发，通常不必为了“开源”单独换许可证。
+一般情况下，不需要为了“把仓库开源”额外改成别的许可证；但你仍需要确认两件事：

-但你需要额外关注：
+1. `LICENSE` 中的版权主体是否就是你希望公开使用的名字
+2. 仓库里的第三方资源、字体、二进制是否都允许再分发

- 字体文件的再分发许可
- `wechat_ipad/ipad859go` 二进制来源与授权
- `resource/` 下业务资料是否适合公开
- 第三方前端静态资源的许可证保留
+相关说明见 [THIRD_PARTY_LICENSES.md](/d:/learn/abot/THIRD_PARTY_LICENSES.md:1)。

-详情见 [THIRD_PARTY_LICENSES.md](/d:/learn/abot/THIRD_PARTY_LICENSES.md:1)。
-
-### 不建议公开提交的内容
+### 不建议直接公开提交的内容

 - `.env`
 - `config.yaml`
- `wechat_ipad/providers/*/runtime_state.toml` 中的真实 `wxid` / `device_id`
+- `wechat_ipad/providers/*/runtime_state.toml`
 - 真实数据库密码、LLM API Key、Webhook Token
+- 未确认授权来源的字体、二进制与业务素材
+
+## 已知仍需你自行确认的事项
+
+以下内容我已经在文档中标出来，但不适合由我直接替你做法律判断：
+
+- `LICENSE` 版权主体是否需要改成你当前对外公开的名称
+- `fonts/` 下字体文件的再分发许可
+- `wechat_ipad/ipad859go` 的来源与授权
+- `resource/` 目录中的业务资料是否适合公开仓库传播

 ## 路线图

-当前更优先的方向不是继续无上限堆新功能，而是继续补工程底座：
+当前更值得优先推进的方向：

- Docker 化与部署规范
- 文档与回归清单
- 插件治理
- 可观测性与任务中心
- 开源边界与资产合规
+- 继续完善 `864 provider` 真机联调与高频接口覆盖
+- 补齐 Docker / 部署回归清单
+- 插件治理、任务中心、可观测性增强
+- 开源资产合规清点

-已整理的工程 backlog 见 [docs/工程优化与Feature清单.md](/d:/learn/abot/docs/工程优化与Feature清单.md:1)。
+已整理的工程规划文档：

-## 贡献与使用说明
+- [docs/工程优化与Feature清单.md](/d:/learn/abot/docs/工程优化与Feature清单.md:1)
+- [docs/wechat_ipad多版本Server适配路线图.md](/d:/learn/abot/docs/wechat_ipad多版本Server适配路线图.md:1)

- 欢迎基于自己的场景二次开发
- 提交前请避免把本地私有配置、运行日志、登录态一并提交
- 涉及平台接口、内容抓取、自动推送等能力时，请自行评估目标平台规则与当地法律要求
+## 使用与贡献说明
+
+- 欢迎按自己的场景二次开发
+- 提交代码前请确认未误带本地私有配置、日志和登录态
+- 涉及内容抓取、自动推送、第三方平台接口的能力，请自行评估合规与风控要求