部署手册

本文档为清海 AI 助理从零开始的完整部署指南，涵盖服务器初始化、三大企业聊天平台（飞书 / 企业微信 / 钉钉）的机器人接入配置。

一、服务器准备

1.1 服务器要求

资源	最低配置	推荐配置
CPU	2 核	4 核
内存	4 GB	8 GB
硬盘	40 GB SSD	80 GB SSD
操作系统	Ubuntu 22.04 LTS	Ubuntu 22.04 LTS
公网 IP	必须	必须
域名	必须（用于 HTTPS 回调）	必须

重要：飞书、企业微信的消息回调均要求 公网可访问的 HTTPS 地址，钉钉 Stream 模式无此要求。

1.2 基础环境安装

bash

# 更新系统包
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y git curl wget nginx certbot python3-certbot-nginx

# 安装 Python 3.11
sudo apt install -y python3.11 python3.11-venv python3.11-dev

# 安装 uv（项目依赖管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env

1.3 安装 MongoDB

bash

# 导入 MongoDB 公钥
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
  sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor

# 添加源
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] \
  https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# 安装并启动
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod

1.4 安装 Qdrant（向量数据库）

bash

# 使用 Docker 方式（推荐）
sudo apt install -y docker.io
sudo systemctl start docker && sudo systemctl enable docker

docker run -d \
  --name qdrant \
  --restart always \
  -p 6333:6333 \
  -v $(pwd)/qdrant_data:/qdrant/storage \
  qdrant/qdrant:latest

1.5 拉取项目代码

bash

# 克隆仓库
git clone https://your-gitlab.com/boss-agi.git /opt/boss-agi
cd /opt/boss-agi

# 安装 Python 依赖
uv sync --all-extras

1.6 配置 HTTPS 证书

bash

# 申请 Let's Encrypt 证书（替换为实际域名）
sudo certbot --nginx -d your-domain.com

# 证书自动续签
sudo systemctl enable certbot.timer

1.7 配置 Nginx 反向代理

编辑 /etc/nginx/sites-available/boss-agi：

nginx

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # 飞书消息回调
    location /webhook/feishu {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 30s;
    }

    # 企业微信消息回调
    location /webhook/wecom {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 30s;
    }
}

bash

sudo ln -s /etc/nginx/sites-available/boss-agi /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

1.8 初始化配置文件

在项目根目录创建 .config.json（参考如下模板，后续各平台会填入对应字段）：

json

{
  "feishu": {
    "app_id": "",
    "app_secret": "",
    "encrypt_key": "",
    "verification_token": "",
    "owner_open_ids": []
  },
  "telegram": {
    "bot_token": "",
    "admin_chat_ids": [],
    "claude_session_id": "",
    "claude_path": "/usr/local/bin/claude",
    "proxy": ""
  },
  "wecom": {
    "corpid": "",
    "agentid": "",
    "secret": "",
    "token": "",
    "encoding_aes_key": ""
  },
  "mongodb": {
    "host": "127.0.0.1",
    "port": 27017,
    "db": "boss_agi"
  },
  "llm_providers": {
    "default": {
      "api_base": "https://api.anthropic.com",
      "api_key": "",
      "model": "claude-sonnet-4-6"
    }
  },
  "embedding": {
    "api_base": "https://api.openai.com/v1",
    "api_key": "",
    "model": "text-embedding-3-small"
  },
  "daemon": {
    "feishu_sync_interval": 1800,
    "heartbeat_interval": 300,
    "workday_only": false
  }
}

二、飞书接入

2.1 整体流程

2.2 创建企业自建应用

打开飞书开放平台：https://open.feishu.cn
使用企业管理员账号登录，进入开发者后台
点击「创建企业自建应用」
填写应用名称（如：清海助理）、描述、上传图标
点击「确认创建」

2.3 添加机器人能力

进入刚创建的应用，点击左侧「添加应用能力」
在能力列表中找到「机器人」，点击「添加」
保存配置

2.4 申请权限

进入左侧「权限管理」→「批量导入」，粘贴以下权限配置：

json

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:chat:readonly",
      "contact:user.base:readonly",
      "contact:department.base:readonly"
    ]
  }
}

点击「下一步」→「确认新增权限」。

2.5 配置事件订阅

进入左侧「事件与回调」→「事件配置」：

订阅方式选择：将事件发送至开发者服务器
请求地址填写：https://your-domain.com/webhook/feishu
消息加密：点击「加密策略」，开启加密，记录生成的 Encrypt Key 和 Verification Token
点击「保存」（保存时会立即验证回调地址是否可达，需先确保服务已启动）

然后点击「添加事件」，搜索并添加：

im.message.receive_v1（接收消息 v2.0）

2.6 获取应用凭证

进入左侧「凭证与基础信息」：

字段	说明	填入 .config.json
App ID	应用唯一标识	`feishu.app_id`
App Secret	应用密钥	`feishu.app_secret`

加密策略页面：

字段	说明	填入 .config.json
Encrypt Key	消息内容加密密钥	`feishu.encrypt_key`
Verification Token	回调签名校验	`feishu.verification_token`

2.7 设置机器人可见范围

进入左侧「版本管理与发布」→「创建版本」：

填写版本号（如 1.0.0）
在「可用性状态」中，选择「部分员工」或「全部员工」
点击「保存并提交审批」（企业管理员审批后生效）

2.8 将凭证填入配置文件

json

{
  "feishu": {
    "app_id": "cli_xxxxxxxxxxxxxxxx",
    "app_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "encrypt_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "verification_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "owner_open_ids": ["ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
  }
}

owner_open_ids 填写机器人 Owner（老板）的飞书 open_id，可在飞书「联系人」→「用户管理」通过 API 查询获得。

2.9 验证接入

启动服务后（见第五节），向机器人发送私聊消息或在已添加机器人的群组 @机器人，观察日志：

bash

tail -f /opt/boss-agi/data/logs/feishu_bot.log

三、企业微信接入

3.1 整体流程

3.2 创建企业自建应用

登录企业微信管理后台：https://work.weixin.qq.com
进入「应用管理」→「自建」→「创建应用」
填写应用 Logo、名称（如：清海 AI）、功能介绍
设置「可见范围」（可指定部门或员工）
点击「创建应用」

3.3 获取核心凭证

凭证	位置	填入 .config.json
企业 ID（CorpID）	管理后台 → 我的企业 → 企业信息 → 企业 ID	`wecom.corpid`
AgentID	应用管理 → 对应应用 → AgentId	`wecom.agentid`
Secret	应用管理 → 对应应用 → Secret → 查看（需手机确认）	`wecom.secret`

3.4 配置接收消息回调

在应用详情页，点击「接收消息」→「设置 API 接收」：

URL：填写 https://your-domain.com/webhook/wecom
Token：自定义字符串（如随机 32 位），填入 .config.json 的 wecom.token
EncodingAESKey：点击「随机生成」，填入 .config.json 的 wecom.encoding_aes_key
消息加密方式：选择「安全模式」（推荐）
点击「保存」（企业微信会即时验证 URL 可达性，需先启动服务）

验证机制：企业微信 GET 请求回调 URL，服务需正确解密 echostr 参数并原样返回，才能通过验证。

3.5 配置可信 IP

在应用详情页「企业可信 IP」一栏，添加服务器的公网 IP 地址，否则调用企业微信接口发送消息时会报错 {"errcode":60020}。

3.6 填入配置文件

json

{
  "wecom": {
    "corpid": "wxxxxxxxxxxxxxxxxx",
    "agentid": "1000002",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token": "your_custom_token_string",
    "encoding_aes_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

3.7 设置应用消息发送权限

在「应用管理」→ 应用详情 → 滚动至「应用功能」：

开启「接收消息」开关
在「消息推送」区域，确认应用有权推送消息给员工

3.8 验证接入

在企业微信客户端找到该应用，向其发送一条消息，观察服务日志：

bash

tail -f /opt/boss-agi/data/logs/wecom_bot.log

四、钉钉接入

4.1 整体流程

4.2 创建企业内部应用

登录钉钉开放平台：https://open-dev.dingtalk.com
进入「应用开发」→「企业内部开发」
点击「创建应用」→ 选择「企业内部应用」
填写应用名称（如：清海 AI 助手）、描述、图标
点击「确认创建」

4.3 添加机器人能力

进入应用，点击「添加应用能力」
找到「机器人」，点击「添加」
在机器人配置页，填写机器人名称和描述

4.4 选择接入模式

模式 A：Stream 模式（推荐）

Stream 模式使用 WebSocket 长连接，无需公网服务器，本地部署可直接使用。

在「消息接收模式」选择「Stream 模式」
无需填写回调地址
服务端使用钉钉官方 SDK 建立持久连接接收消息

模式 B：HTTP 回调模式

需要公网可访问的 HTTPS 地址。

在「消息接收模式」选择「HTTP 模式」
消息接收地址填写：https://your-domain.com/webhook/dingtalk

4.5 获取应用凭证

进入「应用信息」→「应用凭证」：

字段	说明	配置用途
AppKey（ClientID）	应用唯一标识	代码中 `client_id`
AppSecret（ClientSecret）	应用密钥	代码中 `client_secret`

4.6 申请消息权限

进入「权限管理」，申请以下权限：

企业内机器人发送消息（qyapi_robot_sendmsg）
消息通知（必要时）
通讯录读取

4.7 代码集成（Stream 模式）

安装钉钉 Python SDK：

bash

uv add dingtalk-stream

在 scripts/ 下创建 dingtalk_bot.py，核心接入代码：

python

import dingtalk_stream
from scripts.config import load_app_config

def on_message(incoming_message: dingtalk_stream.ChatbotMessage):
    """接收钉钉消息，调用 avatar_core 处理"""
    cfg = load_app_config()
    sender_id = incoming_message.sender_staff_id
    content = incoming_message.text.content.strip()
    # TODO: 接入 avatar_core 对话处理

def start_dingtalk_bot():
    cfg = load_app_config().get("dingtalk", {})
    credential = dingtalk_stream.Credential(
        cfg["client_id"],
        cfg["client_secret"]
    )
    client = dingtalk_stream.DingTalkStreamClient(credential)
    client.register_callback_handler(
        dingtalk_stream.chatbot.ChatbotMessage.TOPIC,
        on_message
    )
    client.start_forever()

在 .config.json 新增钉钉配置段：

json

{
  "dingtalk": {
    "client_id": "dingxxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

4.8 发布应用

进入「版本管理与发布」
点击「创建新版本」
填写版本号、描述
设置「可见范围」
点击「直接发布」（企业内部应用无需审核）

五、服务启动

5.1 启动服务

bash

cd /opt/boss-agi

# 启动主服务（含飞书 Bot、TG Bot、守护进程）
uv run python start_memory.py

# 后台运行
nohup uv run python start_memory.py > data/logs/main.log 2>&1 &
echo $! > /tmp/boss-agi.pid

5.2 配置 systemd 自动启动（推荐）

创建 /etc/systemd/system/boss-agi.service：

ini

[Unit]
Description=Boss AGI - 清海 AI 助理
After=network.target mongod.service

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/boss-agi
ExecStart=/opt/boss-agi/.venv/bin/python start_memory.py
Restart=on-failure
RestartSec=10
StandardOutput=append:/opt/boss-agi/data/logs/main.log
StandardError=append:/opt/boss-agi/data/logs/main.err

[Install]
WantedBy=multi-user.target

bash

sudo systemctl daemon-reload
sudo systemctl enable boss-agi
sudo systemctl start boss-agi
sudo systemctl status boss-agi

5.3 查看运行状态

bash

# 查看主服务日志
tail -f /opt/boss-agi/data/logs/main.log

# 查看飞书 Bot 日志
tail -f /opt/boss-agi/data/logs/feishu_bot.log

# 停止服务
python start_memory.py stop

六、三平台对比

对比项	飞书	企业微信	钉钉
需要公网 IP	✅ 必须	✅ 必须	❌ Stream 模式不需要
需要 HTTPS 域名	✅ 必须	✅ 必须	❌ Stream 模式不需要
回调加密	AES 可选	AES 必须	Stream 内置
权限申请	需管理员审批	即时生效	即时生效
消息类型	富媒体/卡片	文本/卡片	文本/卡片/Markdown
群聊支持	✅	✅	✅
私聊支持	✅	✅	✅

七、常见问题

Q：飞书回调地址保存时提示"请求 URL 无法访问"

确认服务已启动（python start_memory.py）、Nginx 配置正确、443 端口已开放（安全组/防火墙）。

Q：企业微信保存回调提示"openapi 回调地址请求不通过"

确认服务已启动，回调 URL 能被外网访问，且 Token 和 EncodingAESKey 已正确填入 .config.json。

Q：飞书消息发送失败，提示权限不足

检查应用是否已申请 im:message:send_as_bot 权限，且应用版本已发布并生效。

Q：企业微信调用接口报 60020

服务器公网 IP 未加入「企业可信 IP」列表，在企业微信管理后台的应用详情页添加即可。

Q：钉钉 Stream 模式连接断开

SDK 会自动重连，检查 client_id 和 client_secret 是否正确，网络出口是否能访问钉钉 Stream 服务地址。

部署手册 ​

一、服务器准备 ​

1.1 服务器要求 ​

1.2 基础环境安装 ​

1.3 安装 MongoDB ​

1.4 安装 Qdrant（向量数据库） ​

1.5 拉取项目代码 ​

1.6 配置 HTTPS 证书 ​

1.7 配置 Nginx 反向代理 ​

1.8 初始化配置文件 ​

二、飞书接入 ​

2.1 整体流程 ​

2.2 创建企业自建应用 ​

2.3 添加机器人能力 ​

2.4 申请权限 ​

2.5 配置事件订阅 ​

2.6 获取应用凭证 ​

2.7 设置机器人可见范围 ​

2.8 将凭证填入配置文件 ​

2.9 验证接入 ​

三、企业微信接入 ​

3.1 整体流程 ​

3.2 创建企业自建应用 ​

3.3 获取核心凭证 ​

3.4 配置接收消息回调 ​

3.5 配置可信 IP ​

3.6 填入配置文件 ​

3.7 设置应用消息发送权限 ​

3.8 验证接入 ​

四、钉钉接入 ​

4.1 整体流程 ​

4.2 创建企业内部应用 ​

4.3 添加机器人能力 ​

4.4 选择接入模式 ​

模式 A：Stream 模式（推荐） ​

模式 B：HTTP 回调模式 ​

4.5 获取应用凭证 ​

4.6 申请消息权限 ​

4.7 代码集成（Stream 模式） ​

4.8 发布应用 ​

五、服务启动 ​

5.1 启动服务 ​

5.2 配置 systemd 自动启动（推荐） ​

5.3 查看运行状态 ​

六、三平台对比 ​

七、常见问题 ​

部署手册

一、服务器准备

1.1 服务器要求

1.2 基础环境安装

1.3 安装 MongoDB

1.4 安装 Qdrant（向量数据库）

1.5 拉取项目代码

1.6 配置 HTTPS 证书

1.7 配置 Nginx 反向代理

1.8 初始化配置文件

二、飞书接入

2.1 整体流程

2.2 创建企业自建应用

2.3 添加机器人能力

2.4 申请权限

2.5 配置事件订阅

2.6 获取应用凭证

2.7 设置机器人可见范围

2.8 将凭证填入配置文件

2.9 验证接入

三、企业微信接入

3.1 整体流程

3.2 创建企业自建应用

3.3 获取核心凭证

3.4 配置接收消息回调

3.5 配置可信 IP

3.6 填入配置文件

3.7 设置应用消息发送权限

3.8 验证接入

四、钉钉接入

4.1 整体流程

4.2 创建企业内部应用

4.3 添加机器人能力

4.4 选择接入模式

模式 A：Stream 模式（推荐）

模式 B：HTTP 回调模式

4.5 获取应用凭证

4.6 申请消息权限

4.7 代码集成（Stream 模式）

4.8 发布应用

五、服务启动

5.1 启动服务

5.2 配置 systemd 自动启动（推荐）

5.3 查看运行状态

六、三平台对比

七、常见问题