个人 AI 助手部署实战：Docker / 云平台 / 本地三种方式全攻略，10 分钟上线你的专属 Bot！
8/30/2026

文章链接：https://blog.csdn.net/qq_43201350/article/details/163513647

前两篇讲了体验和架构，很多人留言问"怎么部署到我自己的服务器上"。 这篇文章就手把手带你走通三种部署方式——从本地开发到公网上线，全程可复现。

一、三种部署方式对比

方式适用场景成本难度上线时间
Docker Compose个人 VPS、NAS、家里服务器电费/云服务器月费⭐⭐10 分钟
云平台（PaaS）不想管运维，快速上线按量付费 ~50-200/月⭐5 分钟
本地裸机开发调试、离线环境免费⭐⭐⭐20 分钟

二、方式一：Docker Compose（推荐个人使用）

2.1 环境要求

# 操作系统: Ubuntu 22.04 / Debian 12 / CentOS 8+
# Docker >= 24.0
# Docker Compose >= 2.20
# 内存 >= 2GB（推荐 4GB）
# 磁盘 >= 10GB 可用空间

2.2 三步部署

第一步：拉取项目
# 创建目录
mkdir -p /opt/demo-assistant && cd /opt/demo-assistant
 
# 拉取项目代码
git clone https://github.com/demo-org/demo-ai-assistant.git .
 
# 复制配置模板
cp config/template.yaml config/production.yaml
第二步：修改配置
# config/production.yaml
assistant:
  name: "小助"
  owner: "demo-user"
  timezone: "Asia/Shanghai"
  log_level: "info"       # debug | info | warn | error
 
# ========== AI 引擎 ==========
ai:
  provider: "openai"      # 也支持其他兼容接口
  model: "demo-model-v3"
  api_key: "${AI_API_KEY}"     # 从环境变量读取
  base_url: "${AI_BASE_URL}"   # 也支持代理地址
  system_prompt: |
    你是"小助"，一个友好的个人 AI 助手。
    - 回复简洁，不超过 150 字
    - 不确定的事说不知道
    - 涉及金钱/权限的操作一律拒绝
  
  # 对话参数
  default_params:
    temperature: 0.7
    max_tokens: 500
    timeout_ms: 30000
 
  # 上下文窗口
  context:
    max_history: 20        # 最多保留 20 轮对话
    max_tokens: 4000       # 总 token 上限
    ttl_minutes: 60        # 超过 60 分钟无对话 → 清空上下文
 
# ========== 通道配置 ==========
channels:
  # 微信
  wechat:
    enabled: true
    login_method: "qrcode"       # qrcode | padlocal（需要 token）
    # 白名单——只处理这些群和个人（你的机器人不会在别的群乱说话）
    whitelist:
      users:
        - "张三"                  # 你的微信好友备注
        - "李四"
      groups:
        - "Demo项目群"
        - "Demo技术交流群"
    # 哪些群需要被 @ 才回复
    mention_only_groups:
      - "Demo技术交流群"
  
  # 企业通讯工具
  dingtalk:
    enabled: true
    app_key: "${DINGTALK_APP_KEY}"
    app_secret: "${DINGTALK_APP_SECRET}"
    listen:
      # 监听关键词
      keywords: ["@小助", "小助帮忙", "/ai"]
  
  # Telegram
  telegram:
    enabled: false         # 暂时不开
    bot_token: "${TG_BOT_TOKEN}"
 
# ========== 知识库 ==========
knowledge:
  enabled: true
  sources:
    - name: "项目文档"
      type: "local_docs"
      path: "/opt/demo-assistant/knowledge/docs"
      file_types: [".md", ".txt"]
      chunk_size: 500
    - name: "FAQ"
      type: "qa_pairs"
      path: "/opt/demo-assistant/knowledge/faq.yaml"
 
# ========== 插件 ==========
plugins:
  dir: "/opt/demo-assistant/plugins"
  auto_load: true           # 自动加载目录下的插件
  # 默认启用的插件
  enabled:
    - "demo-weather"
    - "demo-todo"
    - "demo-translator"
 
# ========== 定时任务 ==========
schedules:
  - name: "morning-report"
    cron: "0 9 * * *"       # 每天 9:00
    channel: "wechat"
    target:
      group: "Demo项目群"
    message: |
      早上好！☀️ 今日简报：
      {{weather("深圳")}}
      待办: {{todo_list()}}
 
# ========== 安全 ==========
security:
  # 拒绝执行以下操作
  blocked_actions:
    - "转账"
    - "付款"
    - "删除数据库"
    - "rm -rf"
    - "shutdown"
  
  # 敏感操作需要确认
  confirm_actions:
    - "重启服务"
    - "清理缓存"
第三步：配置环境变量
# .env 文件——敏感信息不写进配置文件
cat > .env << 'EOF'
# AI API 密钥
AI_API_KEY=sk-demo-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AI_BASE_URL=https://api.example.com/v1
 
# 企业通讯密钥
DINGTALK_APP_KEY=demo-dingtalk-key-xxxxx
DINGTALK_APP_SECRET=demo-dingtalk-secret-xxxxx
 
# Telegram（可选）
TG_BOT_TOKEN=demo-tg-bot-token-xxxxx
 
# 管理界面密码
ADMIN_PASSWORD=demo-admin-2026
EOF
第四步：启动
# docker-compose.yml
version: '3.8'
 
services:
  # ===== 主服务 =====
  assistant:
    image: demo-ai-assistant:latest
    container_name: demo-assistant
    restart: unless-stopped
    volumes:
      - ./config:/app/config:ro
      - ./knowledge:/opt/demo-assistant/knowledge:ro
      - ./plugins:/opt/demo-assistant/plugins:ro
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - CONFIG_PATH=/app/config/production.yaml
      - TZ=Asia/Shanghai
    env_file:
      - .env
    ports:
      - "3000:3000"     # 管理后台
    depends_on:
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 5s
      retries: 3
 
  # ===== Redis（缓存 + 向量存储） =====
  redis:
    image: redis/redis-stack:7.2.0
    container_name: demo-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    ports:
      - "127.0.0.1:6379:6379"   # 只监听本地
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
 
  # ===== 可选的 Watchtower（自动更新容器） =====
  watchtower:
    image: containrrr/watchtower
    container_name: demo-watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400 --cleanup demo-assistant
    # 每天检查一次镜像更新
 
volumes:
  redis_data:
# 启动所有服务
docker compose up -d
 
# 查看日志
docker compose logs -f assistant
 
# 预期输出：
# [2026-01-20 10:00:01] INFO  加载配置: production.yaml
# [2026-01-20 10:00:02] INFO  Redis 连接成功
# [2026-01-20 10:00:03] INFO  加载知识库: 项目文档 (15 个文档)
# [2026-01-20 10:00:03] INFO  加载知识库: FAQ (42 条问答)
# [2026-01-20 10:00:04] INFO  加载插件: demo-weather v1.0.0
# [2026-01-20 10:00:04] INFO  加载插件: demo-todo v1.0.0
# [2026-01-20 10:00:04] INFO  加载插件: demo-translator v1.0.0
# [2026-01-20 10:00:05] INFO  微信通道: 等待扫码登录...
# [2026-01-20 10:00:06] INFO  钉钉通道: 已连接
# [2026-01-20 10:00:06] INFO  小助 已上线
第五步：扫码登录微信
# 查看微信登录二维码
docker compose logs assistant | grep "qrcode"
# 输出一个终端二维码，用手机微信扫描即可

2.3 日常运维

# 查看运行状态
docker compose ps
 
# 查看实时日志
docker compose logs -f --tail=100 assistant
 
# 重启服务（配置修改后）
docker compose restart assistant
 
# 进入容器调试
docker compose exec assistant sh
 
# 备份数据
tar czf backup-$(date +%Y%m%d).tar.gz ./data ./config ./.env
 
# 更新镜像
docker compose pull assistant
docker compose up -d

三、方式二：云平台一键部署（Fly.io / Railway）

3.1 Fly.io 部署（推荐——有免费额度）

Fly.io 提供每月 5 美元的免费额度，足够个人使用。

# 1. 安装 flyctl
curl -L https://fly.io/install.sh | sh
 
# 2. 登录
flyctl auth login
 
# 3. 在项目目录初始化
cd demo-ai-assistant
flyctl launch

fly.toml 配置：

# fly.toml
app = "demo-ai-assistant"
primary_region = "nrt"  # 东京（离国内近）
 
[build]
  image = "node:20-alpine"
 
[env]
  NODE_ENV = "production"
  CONFIG_PATH = "/app/config/cloud.yaml"
 
[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1
 
[mounts]
  source = "assistant_data"
  destination = "/app/data"
 
  source = "assistant_knowledge"
  destination = "/opt/demo-assistant/knowledge"
 
# 环境变量（敏感信息用 secrets）
[[vm]]
  memory = "512mb"
  cpu_kind = "shared"
  cpus = 1
# 设置密钥——不写入配置文件
flyctl secrets set \
  AI_API_KEY=sk-demo-xxxxxxxxxxxxxx \
  AI_BASE_URL=https://api.example.com/v1 \
  DINGTALK_APP_KEY=demo-key \
  DINGTALK_APP_SECRET=demo-secret \
  ADMIN_PASSWORD=demo-pwd
 
# 部署
flyctl deploy
 
# 查看日志
flyctl logs
 
# 查看状态
flyctl status
 
# 访问管理后台
flyctl open
# 自动打开 https://demo-ai-assistant.fly.dev

3.2 Railway 部署（最简单——点点点就行）

  1. Fork 项目到 GitHub → 打开 Railway

  2. New Project → Deploy from GitHub repo → 选择项目

  3. 添加环境变量（Settings → Variables）

  4. 自动构建并上线

# 唯一需要做的事：在 Railway Dashboard 设置这些变量
AI_API_KEY = sk-demo-xxxxxxxxxxx
AI_BASE_URL = https://api.example.com/v1
DINGTALK_APP_KEY = demo-key
DINGTALK_APP_SECRET = demo-secret

Railway 会自动检测 package.json 中的启动脚本并构建部署。

3.3 云平台注意事项

注意点说明
微信通道需要 qrcode 模式登录，确保容器有终端或获取二维码 URL
时区设置环境变量 TZ=Asia/Shanghai
数据持久化云平台必须挂载 Volume，否则重启数据丢失
健康检查配 /api/health 端点，云平台会自动重启不健康的实例
国内访问Fly.io 东京区域延迟 50-80ms，Railway 需要代理

四、方式三：本地裸机部署（开发调试专用）

4.1 安装依赖

# macOS
brew install node@20 pnpm redis
 
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs redis-server
sudo npm install -g pnpm
 
# Windows
# 下载 Node.js 安装包 → 安装 → PowerShell 中运行
# npm install -g pnpm
# 另装 Redis for Windows 或 WSL2

4.2 安装项目

# 克隆项目
git clone https://github.com/demo-org/demo-ai-assistant.git
cd demo-ai-assistant
 
# 安装依赖（Monorepo 自动处理）
pnpm install
 
# 初始化子包
pnpm build:all

4.3 开发模式启动

# 启动 Redis（如果还没启动）
redis-server --daemonize yes
 
# 复制配置
cp config/template.yaml config/local.yaml
 
# 编辑 local.yaml，配置 AI API key 和通道信息
 
# 启动开发服务器（热重载）
pnpm dev
 
# 输出：
# [dev] 管理后台: http://localhost:3000
# [dev] API 服务:  http://localhost:3001
# [dev] 微信通道: 等待扫码...

4.4 调试技巧

# 1. 只启动某个通道进行调试
pnpm dev --channel wechat
 
# 2. 开启调试日志
LOG_LEVEL=debug pnpm dev
 
# 3. 模拟消息——不需要真实 IM 也能测试
pnpm cli mock-message \
  --channel wechat \
  --from "测试用户" \
  --text "今天天气怎么样" \
  --type text
 
# 你会看到完整的管道处理日志：
# [Pipeline] ── 收到消息: 今天天气怎么样
# [PreProcess] 安全检查通过
# [Route] 匹配到插件: demo-weather (priority=60)
# [Plugin:demo-weather] 提取城市: 深圳
# [Plugin:demo-weather] 查询天气...
# [Plugin:demo-weather] AI 润色回复...
# [PostProcess] 回复预览: "今天深圳晴天，温度 25°C..."
# [Reply] 模拟发送成功

4.5 本地运行测试

# 跑单元测试
pnpm test
 
# 跑单个模块的测试
pnpm test -- packages/plugins/demo-weather
 
# 跑 E2E 测试（需要先启动 dev server）
pnpm test:e2e
 
# 覆盖率报告
pnpm test:coverage

五、HTTPS反向代理（公网访问必备）

如果你部署在 VPS 上，需要通过Nginx反代并加 HTTPS：

5.1 安装 Nginx + Certbot

# Ubuntu
sudo apt install -y nginx certbot python3-certbot-nginx
 
# 配置 Nginx
sudo vim /etc/nginx/sites-available/demo-assistant
# /etc/nginx/sites-available/demo-assistant
server {
    listen 80;
    server_name assistant.example.com;
 
    client_max_body_size 10m;
 
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}
# 启用站点
sudo ln -s /etc/nginx/sites-available/demo-assistant /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
 
# 申请 HTTPS 证书
sudo certbot --nginx -d assistant.example.com
 
# 验证自动续期
sudo certbot renew --dry-run

5.2 防火墙设置

# 只开放必要端口
sudo ufw allow 22    # SSH
sudo ufw allow 80    # HTTP
sudo ufw allow 443   # HTTPS
sudo ufw enable
 
# 确认 Redis 不对外开放
sudo ufw status
# 应该只有 22/80/443 是开放的

六、常见问题排查

Q1：微信扫码后显示"登录环境异常"

原因: 微信 Web 协议对非官方客户端有限制

解决方案:
1. 使用手机 4G 流量扫码（不要用 WiFi）
2. 降低消息发送频率（加 2-3 秒间隔）
3. 备选方案：用 padlocal 协议（需 token，更稳定但付费）

Q2：Docker 启动后管理后台打不开

# 检查容器是否运行
docker compose ps
 
# 检查端口占用
sudo ss -tlnp | grep 3000
 
# 查看容器内服务是否启动
docker compose logs assistant --tail 20
 
# 常见原因：.env 文件缺失 AI_API_KEY
echo $AI_API_KEY  # 确认环境变量存在

Q3：AI 回复很慢（>10 秒）

原因和解决：
1. API 地址在国外 → 换国内代理或 Mirror
2. 模型太大 → 换轻量模型
3. Redis 没启动 → 知识库每次都重算向量
4. 上下文太长 → 降低 max_history

# 调优建议
ai:
  model: "demo-model-light"     # 轻量模型更快
  default_params:
    timeout_ms: 15000           # 别设太长
  context:
    max_history: 10             # 减少上下文
    max_tokens: 2000

Q4：云平台部署后微信无法登录

原因: 云平台容器没有 TTY（终端），无法显示扫码二维码

解决方案:
1. 使用 --qrcode-terminal 参数生成终端二维码
2. 或者输出二维码 URL，用浏览器打开扫码
3. Fly.io 可以用 flyctl ssh console 进入容器

七、总结

三种方式打分

维度Docker Compose云平台裸机
上手速度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
可控性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
稳定性⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
成本⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
适合人群有 VPS 的个人不想管运维开发者调试

我的推荐

如果你有 VPS →  选 Docker Compose
  省事省心，数据在你自己手里，10 分钟搞定。

如果你想最省事 → 选 Fly.io / Railway
  一键部署，HTTPS 自动配，不用管服务器。

如果你在开发 → 选本地裸机
  热重载 + 模拟消息，改一行代码立刻看效果。
AI部署