263 lines
9.1 KiB
Markdown
263 lines
9.1 KiB
Markdown
# DobotAI DingTalk Docker 部署手册
|
||
|
||
> 适用范围:DobotAI 的 Docker Compose 部署。容器名固定为 `dobotai-dingtalk`,数据库容器名固定为 `dobotai-postgres`。
|
||
>
|
||
> 本文面向测试/预发布。生产必须使用已验收的同一镜像、独立备份和独立审批,禁止在生产重新编译。
|
||
|
||
## 1. 定位
|
||
|
||
DobotAI 是钉钉渠道的对话编排与交付层,不是知识库、文档解析器或模型平台。
|
||
|
||
```text
|
||
DobotAI 负责:
|
||
钉钉 Stream、富文本/图片、会话映射、WeKnora Agent 调用、卡片交付、
|
||
/think、/setting、覆盖判定、Support Case、反馈、渠道审计。
|
||
|
||
DobotAI 不负责:
|
||
WeKnora 文档/Chunk/向量/图谱/解析/模型;钉钉应用创建;知识库治理。
|
||
```
|
||
|
||
## 2. Docker 架构
|
||
|
||
```text
|
||
钉钉用户/群
|
||
│ DingTalk Stream(出站长连接)
|
||
▼
|
||
┌────────────────────────────────────────┐
|
||
│ dobotai-dingtalk │
|
||
│ 消息、会话、卡片、覆盖与支持流程 │
|
||
│ 仅映射到宿主机 127.0.0.1:8090 │
|
||
└───────┬──────────────────────┬───────────┘
|
||
│ Compose 网络 │ host.docker.internal
|
||
▼ ▼
|
||
┌────────────────────┐ 已有 WeKnora 服务
|
||
│ dobotai-postgres │ Agent / 检索 / 知识 / 模型
|
||
│ dobotai 独立数据库 │
|
||
│ 命名卷持久化 │
|
||
└────────────────────┘
|
||
```
|
||
|
||
Compose 管理的资源:
|
||
|
||
| 资源 | 名称 | 数据策略 |
|
||
| --- | --- | --- |
|
||
| 应用容器 | `dobotai-dingtalk` | 可重建,不保存业务数据卷 |
|
||
| PostgreSQL容器 | `dobotai-postgres` | 可重建,数据在命名卷 |
|
||
| PostgreSQL命名卷 | `dobotai-postgres-data` | 持久数据,禁止常规删除 |
|
||
| Compose网络 | `dobotai-network` | 应用与数据库内部通信 |
|
||
| 宿主机密钥目录 | `<DOBOTAI_HOME>/secrets` | bind mount,不进入Git |
|
||
|
||
关键Compose属性:
|
||
|
||
```yaml
|
||
services:
|
||
dobotai-postgres:
|
||
container_name: dobotai-postgres
|
||
volumes:
|
||
- dobotai-postgres-data:/var/lib/postgresql/data
|
||
|
||
dobotai-dingtalk:
|
||
container_name: dobotai-dingtalk
|
||
depends_on:
|
||
dobotai-postgres:
|
||
condition: service_healthy
|
||
ports:
|
||
- "127.0.0.1:8090:8090"
|
||
extra_hosts:
|
||
- "host.docker.internal:host-gateway"
|
||
```
|
||
|
||
应用不使用 `network_mode: host`:它以`dobotai-postgres:5432`访问Compose数据库,以`http://host.docker.internal:8080`访问宿主机的WeKnora。
|
||
|
||
## 3. 自动安装准备
|
||
|
||
`install-docker.sh`自动完成:
|
||
|
||
```text
|
||
检查 Docker、Docker Compose 和已导入的候选镜像
|
||
创建 <DOBOTAI_HOME>/container、config、secrets、backups、migrations
|
||
生成权限0600的 config/postgres.env 与 config/dobotai.env
|
||
生成独立数据库密码、Ingress Token、Admin Token
|
||
创建并启动 dobotai-postgres
|
||
等待 PostgreSQL healthcheck
|
||
按顺序应用 db/migrations/*.up.sql
|
||
在 dobotai_schema_migrations 记录版本、名称和时间
|
||
安装 configure / start / bind-admin 三条短命令
|
||
```
|
||
|
||
它不会:
|
||
|
||
```text
|
||
启动尚未配置的钉钉应用容器
|
||
覆盖已有配置或数据库数据
|
||
删除任何 Docker 卷
|
||
输出密码、API Key、Token 或连接串
|
||
```
|
||
|
||
默认安装根目录:
|
||
|
||
```text
|
||
/opt/dobotai
|
||
├── container/ Compose、脚本、SQL迁移、运行参数
|
||
├── config/ dobotai.env、postgres.env(0600)
|
||
├── secrets/ DobotAI SecretStore(0700)
|
||
└── backups/ 逻辑备份和SHA清单
|
||
```
|
||
|
||
可以用`DOBOTAI_HOME=/绝对路径`改安装位置。测试环境建议使用独立目录,例如`/opt/dobotai-test-compose`。
|
||
|
||
## 4. 前置条件
|
||
|
||
```text
|
||
部署用户具有 sudo 和 Docker daemon 访问权限
|
||
宿主机 WeKnora 已健康,容器可经 host.docker.internal:8080 访问
|
||
```
|
||
|
||
Docker与Docker Compose缺失时由根安装脚本自动安装(当前支持APT系统)。不必手工构建、导入或命名镜像。
|
||
|
||
## 5. 全新安装
|
||
|
||
从源码仓库克隆后,进入仓库根目录执行唯一安装入口:
|
||
|
||
```bash
|
||
sudo bash ./install-docker.sh
|
||
```
|
||
|
||
脚本内部以当前Git提交构建固定内部镜像名:
|
||
|
||
```text
|
||
dobotai-dingtalk:local-<当前Git短SHA>
|
||
```
|
||
|
||
镜像名、PostgreSQL镜像和构建元数据只由根目录`install-docker.sh`维护,用户不传`DOBOTAI_IMAGE`。脚本完成后数据库和迁移已就绪,应用尚未启动。然后执行:
|
||
|
||
构建期Go依赖使用脚本内置的公开模块代理`https://goproxy.cn,direct`;它只存在于镜像构建命令,不写入DobotAI运行配置。
|
||
|
||
```bash
|
||
sudo dobotai-dingtalk-configure
|
||
```
|
||
|
||
配置器逐项显示用途和脱敏格式示例;已有值不会回显,直接回车表示保留。数据库连接串、数据库密码、Ingress Token和Admin Token由安装脚本生成,交互配置器不要求输入。
|
||
|
||
主要业务连接配置:
|
||
|
||
| 变量 | 用途 | 示例 |
|
||
| --- | --- | --- |
|
||
| `WEKNORA_BASE_URL` | Docker内访问宿主机WeKnora | `http://host.docker.internal:8080` |
|
||
| `WEKNORA_API_KEY` | DobotAI专用WeKnora API Key | `<你的WeKnora API Key>` |
|
||
| `DOBOTAI_TENANT_KEY` | DobotAI租户隔离键 | `dobotai` |
|
||
| `DOBOTAI_AGENT_BINDINGS` | 渠道到WeKnora Agent映射 | `{"dingtalk:*":"你的Agent ID"}` |
|
||
| `DINGTALK_CLIENT_ID` | 钉钉应用Client ID/AppKey | `dingxxxxxxxx` |
|
||
| `DINGTALK_CLIENT_SECRET` | 钉钉应用Secret/AppSecret | `<你的钉钉 AppSecret>` |
|
||
|
||
配置器成功后自动启动`dobotai-dingtalk`,并检查PostgreSQL健康、`http://127.0.0.1:8090/healthz`和容器运行状态。
|
||
|
||
## 7. 首位管理员绑定
|
||
|
||
仅在租户没有有效管理员时执行:
|
||
|
||
```bash
|
||
sudo dobotai-dingtalk-bind-admin
|
||
```
|
||
|
||
终端显示10分钟有效的一次性六码。候选管理员私聊钉钉机器人:
|
||
|
||
```text
|
||
/setting <六码绑定码>
|
||
```
|
||
|
||
终端自动确认后写入`super_admin/active`。已有管理员时命令拒绝执行,防止意外提权。
|
||
|
||
## 8. 迁移现有DobotAI实例
|
||
|
||
旧实例已有Turn、会话、Support Case、管理员或反馈时,不能直接新建空库后切换。先安装目标Compose基础设施,再运行:
|
||
|
||
```bash
|
||
sudo DOBOTAI_HOME=/opt/dobotai-compose \
|
||
SOURCE_POSTGRES_CONTAINER=dobotai-test-postgres \
|
||
SOURCE_APP_CONTAINER=dobotai-dingtalk \
|
||
SOURCE_DOBOTAI_ENV=/etc/dobotai-test/dobotai.env \
|
||
/opt/dobotai-compose/container/migrate-existing-database.sh
|
||
```
|
||
|
||
迁移脚本固定顺序:
|
||
|
||
```text
|
||
启动目标 dobotai-postgres 并等待健康
|
||
→ 停止并改名旧应用容器(不删除)
|
||
→ pg_dump -Fc 导出旧数据库
|
||
→ pg_restore --list 验证备份可读
|
||
→ 写入备份SHA-256
|
||
→ 复制旧应用配置,只替换数据库、监听和WeKnora地址
|
||
→ 恢复到 dobotai-postgres-data
|
||
→ 应用缺失迁移
|
||
→ 启动新 dobotai-dingtalk
|
||
→ 健康失败则恢复旧容器名称和旧容器
|
||
```
|
||
|
||
源数据库不会删除。成功后旧应用容器会以`*-legacy-*`保留,确认稳定前不得删除旧容器或旧数据库。
|
||
|
||
## 9. 数据库迁移
|
||
|
||
DobotAI应用本身不扫描SQL。安装/迁移流程由:
|
||
|
||
```bash
|
||
sudo /opt/dobotai/container/apply-migrations.sh
|
||
```
|
||
|
||
执行`migrations/*.up.sql`,每个成功迁移在同一事务写入:
|
||
|
||
```text
|
||
dobotai_schema_migrations(version, name, applied_at)
|
||
```
|
||
|
||
任何数据库升级前都必须有经`pg_restore --list`验证的逻辑备份。`.down.sql`只能在审查通过后用于数据库回滚,不能用应用镜像回滚替代数据库回滚。
|
||
|
||
## 10. 日常运行与升级
|
||
|
||
```bash
|
||
# 健康与版本
|
||
curl --noproxy '*' -fsS http://127.0.0.1:8090/healthz
|
||
curl --noproxy '*' -fsS http://127.0.0.1:8090/version
|
||
|
||
# Compose状态
|
||
sudo docker compose --env-file /opt/dobotai/container/runtime.env \
|
||
-f /opt/dobotai/container/compose.yaml ps
|
||
|
||
# 日志:不要转发含用户内容或凭据的原始上下文
|
||
sudo docker logs --since 10m dobotai-dingtalk
|
||
|
||
# 数据库状态
|
||
sudo docker inspect -f '{{.State.Health.Status}}|{{.RestartCount}}' dobotai-postgres
|
||
```
|
||
|
||
升级顺序:导入候选镜像 → 备份并应用必要迁移 → 更新`runtime.env`中的`DOBOTAI_IMAGE` → 执行:
|
||
|
||
```bash
|
||
sudo dobotai-dingtalk-start
|
||
```
|
||
|
||
应用健康失败时启动器恢复上一应用镜像;数据库迁移仍必须按审查过的SQL回滚流程处理。
|
||
|
||
## 11. 覆盖判定边界
|
||
|
||
```text
|
||
有结构化引用 → covered_has_references
|
||
实际检索过但没有引用 → uncovered_no_references → Support Case
|
||
明确无权威知识/无答案 → uncovered_explicit_no_answer → Support Case
|
||
图片未检索、纯视觉识别 → covered_visual_recognition
|
||
文本未检索、闲聊/普通非知识响应 → covered_non_knowledge_response
|
||
```
|
||
|
||
因此“在吗”“你好”“谢谢”等未触发知识检索的文本不会创建Support Case或发送未覆盖提醒。
|
||
|
||
## 12. 禁止操作
|
||
|
||
```text
|
||
docker compose down -v
|
||
docker volume rm dobotai-postgres-data
|
||
docker system prune --volumes
|
||
把 config/*.env、secrets/、备份Dump、真实Token或凭据提交Git
|
||
在生产重新编译或使用未经测试的镜像
|
||
```
|