DobotAI DingTalk Docker 部署手册
适用范围:DobotAI 的 Docker Compose 部署。容器名固定为
dobotai-dingtalk,数据库容器名固定为dobotai-postgres。本文面向测试/预发布。生产必须使用已验收的同一镜像、独立备份和独立审批,禁止在生产重新编译。
1. 定位
DobotAI 是钉钉渠道的对话编排与交付层,不是知识库、文档解析器或模型平台。
DobotAI 负责:
钉钉 Stream、富文本/图片、会话映射、WeKnora Agent 调用、卡片交付、
/think、/setting、覆盖判定、Support Case、反馈、渠道审计。
DobotAI 不负责:
WeKnora 文档/Chunk/向量/图谱/解析/模型;钉钉应用创建;知识库治理。
2. Docker 架构
钉钉用户/群
│ 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属性:
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自动完成:
检查 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 三条短命令
它不会:
启动尚未配置的钉钉应用容器
覆盖已有配置或数据库数据
删除任何 Docker 卷
输出密码、API Key、Token 或连接串
默认安装根目录:
/opt/dobotai
├── container/ Compose、脚本、SQL迁移、运行参数
├── config/ dobotai.env、postgres.env(0600)
├── secrets/ DobotAI SecretStore(0700)
└── backups/ 逻辑备份和SHA清单
可以用DOBOTAI_HOME=/绝对路径改安装位置。测试环境建议使用独立目录,例如/opt/dobotai-test-compose。
4. 前置条件
部署用户具有 sudo 和 Docker daemon 访问权限
宿主机 WeKnora 已健康,容器可经 host.docker.internal:8080 访问
Docker与Docker Compose缺失时由根安装脚本自动安装(当前支持APT系统)。不必手工构建、导入或命名镜像。
5. 全新安装
从源码仓库克隆后,进入仓库根目录执行唯一安装入口:
sudo bash ./install-docker.sh
脚本内部以当前Git提交构建固定内部镜像名:
dobotai-dingtalk:local-<当前Git短SHA>
镜像名、PostgreSQL镜像和构建元数据只由根目录install-docker.sh维护,用户不传DOBOTAI_IMAGE。脚本完成后数据库和迁移已就绪,应用尚未启动。然后执行:
构建期Go依赖使用脚本内置的公开模块代理https://goproxy.cn,direct;它只存在于镜像构建命令,不写入DobotAI运行配置。
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. 首位管理员绑定
仅在租户没有有效管理员时执行:
sudo dobotai-dingtalk-bind-admin
终端显示10分钟有效的一次性六码。候选管理员私聊钉钉机器人:
/setting <六码绑定码>
终端自动确认后写入super_admin/active。已有管理员时命令拒绝执行,防止意外提权。
8. 迁移现有DobotAI实例
旧实例已有Turn、会话、Support Case、管理员或反馈时,不能直接新建空库后切换。先安装目标Compose基础设施,再运行:
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
迁移脚本固定顺序:
启动目标 dobotai-postgres 并等待健康
→ 停止并改名旧应用容器(不删除)
→ pg_dump -Fc 导出旧数据库
→ pg_restore --list 验证备份可读
→ 写入备份SHA-256
→ 复制旧应用配置,只替换数据库、监听和WeKnora地址
→ 恢复到 dobotai-postgres-data
→ 应用缺失迁移
→ 启动新 dobotai-dingtalk
→ 健康失败则恢复旧容器名称和旧容器
源数据库不会删除。成功后旧应用容器会以*-legacy-*保留,确认稳定前不得删除旧容器或旧数据库。
9. 数据库迁移
DobotAI应用本身不扫描SQL。安装/迁移流程由:
sudo /opt/dobotai/container/apply-migrations.sh
执行migrations/*.up.sql,每个成功迁移在同一事务写入:
dobotai_schema_migrations(version, name, applied_at)
任何数据库升级前都必须有经pg_restore --list验证的逻辑备份。.down.sql只能在审查通过后用于数据库回滚,不能用应用镜像回滚替代数据库回滚。
10. 日常运行与升级
# 健康与版本
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 → 执行:
sudo dobotai-dingtalk-start
应用健康失败时启动器恢复上一应用镜像;数据库迁移仍必须按审查过的SQL回滚流程处理。
11. 覆盖判定边界
有结构化引用 → covered_has_references
实际检索过但没有引用 → uncovered_no_references → Support Case
明确无权威知识/无答案 → uncovered_explicit_no_answer → Support Case
图片未检索、纯视觉识别 → covered_visual_recognition
文本未检索、闲聊/普通非知识响应 → covered_non_knowledge_response
因此“在吗”“你好”“谢谢”等未触发知识检索的文本不会创建Support Case或发送未覆盖提醒。
12. 禁止操作
docker compose down -v
docker volume rm dobotai-postgres-data
docker system prune --volumes
把 config/*.env、secrets/、备份Dump、真实Token或凭据提交Git
在生产重新编译或使用未经测试的镜像