Files
dobotai-platform/deploy/dobotai-dingtalk/README.md

263 lines
9.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
在生产重新编译或使用未经测试的镜像
```