Files
dobotai-platform/deploy/dobotai-dingtalk

DobotAI DingTalk 容器部署手册

适用范围:DobotAI 测试环境的容器化运行。容器和 Compose 服务名固定为 dobotai-dingtalk。 本文不授权生产部署;生产必须使用已验收的同一镜像、独立备份和独立变更审批。

1. 定位

DobotAI 是钉钉渠道的对话编排与交付层,不是知识库或文档解析平台。

它负责:

  • 接收钉钉 Stream 消息、富文本和图片;
  • 将请求路由到 WeKnora Agent,并维护渠道会话;
  • 通过钉钉 AI 卡片或 Markdown 流式交付回答;
  • 处理 /think、/setting 等渠道命令;
  • 保存 Turn、会话映射、覆盖判定、Support Case、反馈和审计数据;
  • 对“真实检索过但没有引用”的回答创建未覆盖提醒;
  • 将 resource:// 图片按私有 OSS 规则安全外发。

它不负责:

  • WeKnora 文档、Chunk、向量、图谱、解析或模型运行;
  • WeKnora Agent 的知识检索策略;
  • 直接暴露 PostgreSQL、WeKnora 或对象存储到公网;
  • 替代钉钉应用、机器人或群权限配置。

2. 架构

钉钉用户 / 群
      │  DingTalk Stream
      ▼
┌──────────────────────────────────────┐
│ dobotai-dingtalk 容器                │
│  - 消息解析、会话编排、卡片流式交付 │
│  - /think、/setting、首位管理员绑定 │
│  - 覆盖判定、Support Case、审计      │
└───────┬──────────────────┬───────────┘
        │                  │
        │ HTTP Agent Chat  │ PostgreSQL
        ▼                  ▼
   WeKnora 服务        DobotAI 独立数据库
   - Agent/检索        - Turn / 会话 / 覆盖判定
   - 文档/Chunk        - Support Case / 反馈 / 设置
   - 模型与解析

2.1 容器边界

资源 归属 是否由本容器创建/删除
dobotai-dingtalk DobotAI应用进程 是,容器可重建
DobotAI PostgreSQL 独立数据服务 否,保留现有数据卷
WeKnora 独立知识服务 否
/var/lib/dobotai-test/secrets 宿主机密钥目录 仅挂载读写,不迁移、不输出
/etc/dobotai-test/dobotai.env 受保护运行配置 Docker读取,脚本原子更新

测试环境的 PostgreSQL、WeKnora 已通过宿主机回环地址提供服务,因此 Compose 使用 network_mode: host。这不是新开公网端口:DobotAI仍按 DOBOTAI_LISTEN_ADDR 监听,默认是 127.0.0.1:8090。

2.2 容器安全属性

Compose 固定启用:

容器名:dobotai-dingtalk
网络:host(仅兼容现有测试宿主机回环依赖)
运行身份:与原 dobotai-test 服务用户相同的 UID:GID
根文件系统:只读
临时写入:仅 /tmp tmpfs
额外权限:no-new-privileges
重启策略:unless-stopped

对应的关键 Compose 配置如下;不要为避免端口冲突额外添加 ports: 映射:

services:
  dobotai-dingtalk:
    container_name: dobotai-dingtalk
    network_mode: host
    read_only: true
    restart: unless-stopped

3. 安装前检查

安装操作人员需要具备测试服务器的 sudo 和 Docker 权限。开始前确认:

1. 已构建或导入经审查的 DobotAI 镜像;
2. 现有 /etc/dobotai-test/dobotai.env 存在且权限为 0600;
3. 现有密钥目录 /var/lib/dobotai-test/secrets 存在;
4. DobotAI PostgreSQL 与 WeKnora 已健康;
5. 已记录当前原生服务二进制SHA和运行状态;
6. 如本版本包含 SQL 迁移,已先完成逻辑备份与迁移演练。

不要执行:

docker compose down -v
docker volume rm / prune
删除 PostgreSQL / WeKnora 数据卷
将密钥、数据库连接串或 API Key 写入命令行、日志或 Git

4. 构建和导入镜像

在已审查且工作树干净的源码目录构建。示例中的值均为占位符:

docker build \
  --build-arg VERSION=test-<commit-short> \
  --build-arg COMMIT_SHA=<完整提交SHA> \
  --build-arg BUILD_TIME=<UTC时间> \
  -t dobotai-dingtalk:test-<commit-short> .

跨主机传输时先保存镜像归档并记录 SHA-256;测试服务器导入后必须复核归档哈希和镜像标签。生产不得在目标机重新编译,应使用已测试的同一镜像归档或不可变镜像摘要。

5. 安装容器资产(不切换服务)

将本目录、候选镜像和已核验的归档放到测试服务器的受控发布目录。确认镜像已经 docker load 后执行:

sudo DOBOTAI_IMAGE=dobotai-dingtalk:test-<commit-short> \
  bash ./install-test.sh

该脚本会:

1. 检查候选镜像、现有 env 与密钥目录;
2. 备份原生 DobotAI 二进制和 systemd Unit,并写入 SHA-256;
3. 安装 Compose、配置器、启动器和绑定脚本;
4. 生成权限 0600 的 /opt/dobotai-test/container/runtime.env;
5. 保持原生 dobotai-test.service 继续运行。

它不会读取或打印环境变量值、不会修改数据库、不会启动容器。

6. 配置并启动

日常只需要执行:

sudo dobotai-dingtalk-configure

该命令交互更新 /etc/dobotai-test/dobotai.env。每项都会显示用途和脱敏格式示例;已配置的值永不回显,直接回车表示保留。

环境变量 用途 格式示例
DATABASE_URL DobotAI独立PostgreSQL连接串,不得填写WeKnora数据库 postgres://USER:<数据库密码>@127.0.0.1:55432/dobotai_test?sslmode=disable
WEKNORA_BASE_URL 测试WeKnora地址 http://127.0.0.1:8080
WEKNORA_API_KEY DobotAI使用的WeKnora API密钥 <你的WeKnora API Key>
DOBOTAI_INGRESS_TOKEN /v1/qa调用令牌 <随机长字符串>
DOBOTAI_TENANT_KEY 与既有DobotAI数据一致的租户键 dobotai-test
DOBOTAI_AGENT_BINDINGS 钉钉会话到WeKnora Agent的映射 {"dingtalk:*":"你的Agent ID"}
DINGTALK_CLIENT_ID 钉钉应用Client ID/AppKey dingxxxxxxxx
DINGTALK_CLIENT_SECRET 钉钉应用Client Secret/AppSecret <你的钉钉 AppSecret>

保存成功后,配置器自动调用启动器:

停止原生 dobotai-test.service
→ 启动 dobotai-dingtalk
→ 检查 http://127.0.0.1:8090/healthz
→ 健康成功后禁用原生服务

首次容器启动失败会恢复原生服务;容器版本升级失败会恢复上一容器镜像。

7. 首位管理员绑定

仅当该租户不存在有效管理员时执行:

sudo dobotai-dingtalk-bind-admin

终端会显示一个10分钟有效的随机六码。候选管理员必须私聊钉钉机器人发送:

/setting <六码绑定码>

验证成功后,终端自动写入 super_admin/active 并退出。已有有效管理员时命令拒绝执行,防止借由该入口追加管理员或意外提权。

8. 覆盖判定与未覆盖提醒

覆盖判定基于真实的 knowledge_searched 工具事件和结构化引用,不按关键词猜测。

场景 覆盖结果 是否创建 Support Case
有引用 covered_has_references 否
实际检索过但无引用 uncovered_no_references 是
明确无权威知识/无答案 uncovered_explicit_no_answer 是
图片未检索、纯视觉识别 covered_visual_recognition 否
文本未检索、闲聊或普通非知识响应 covered_non_knowledge_response 否

因此“在吗”“你好”“谢谢”等未触发知识检索的文本不会产生未覆盖提醒;真正检索过但没有权威引用的问题仍会进入人工支持流程。

9. 数据库迁移门禁

DobotAI进程只连接数据库,不会自动发现或执行 SQL 迁移。包含新迁移的版本必须在容器替换前由发布流程显式完成:

1. 对 DobotAI PostgreSQL 做逻辑备份;
2. 使用 pg_restore --list 验证备份非空;
3. 在事务中执行已审查的 .up.sql;
4. 向 dobotai_schema_migrations 写入对应 version/name/applied_at;
5. 查询约束、列或索引确认生效;
6. 再替换容器镜像并进行健康与业务验收。

000021_coverage_non_knowledge_response_reason 是一个示例:它只扩展 coverage_decisions.reason_code 的 CHECK 约束,不回写历史Turn、覆盖判定或Support Case。

10. 日常检查

# 健康检查
curl --noproxy '*' -fsS http://127.0.0.1:8090/healthz

# 运行版本
curl --noproxy '*' -fsS http://127.0.0.1:8090/version

# 容器状态与重启次数
sudo docker inspect -f '{{.Config.Image}}|{{.State.Running}}|{{.RestartCount}}' dobotai-dingtalk

# 最近日志(不要复制含敏感内容的原始上下文)
sudo docker logs --since 10m dobotai-dingtalk

验收至少应同时满足:

容器 running,重启次数为0;
/healthz 返回 ok;
/version 的 commit_sha 与发布记录一致;
钉钉 Stream 仅启动一个消费者;
旧 dobotai-test.service 为 inactive + disabled;
目标业务路径已由真实钉钉消息验证。

11. 升级与回滚

升级

构建/导入经审查的新镜像
→ 备份DobotAI PostgreSQL
→ 应用并记录必要迁移
→ 将 runtime.env 中的 DOBOTAI_IMAGE 更新为新标签
→ 执行 sudo dobotai-dingtalk-start
→ 健康、版本、日志、钉钉真实消息验收

注意拼写:数据库和应用名称是 DobotAI;上述流程中的镜像名为 dobotai-dingtalk。

自动回滚

启动器会保存替换前的容器镜像:

首次容器化失败:停止候选容器,恢复原生服务;
后续容器升级失败:停止候选容器,恢复上一容器镜像。

数据库迁移不能仅靠容器回滚撤销。只有经过审查且已验证的 .down.sql 才可用于数据库回滚;任何数据恢复都必须先确认备份可用。

12. 明确非目标

不容器化或重建 WeKnora;
不容器化或删除 DobotAI PostgreSQL;
不重新启用已删除的网页管理面;
不在生产环境复用测试凭据、测试镜像或未验收的迁移;
不把密钥、Token、连接串、钉钉凭据写入 Git、命令行或日志。