Files

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
在生产重新编译或使用未经测试的镜像