微信机器人-webhook技术文档_04-Docker-Compose部署与生产化配置

Docker Compose 部署与生产化配置

1. 为什么推荐 Docker Compose

单条 docker run 命令适合快速测试，但长期运行建议使用 Docker Compose。

Compose 的优势：

配置集中保存在文件中。
重启、停止、升级更清晰。
环境变量不容易遗漏。
日志目录、端口映射可维护。
适合放入内部运维文档。

对于 wechatbot-webhook 这类需要长期保持登录态的服务，Compose 更适合生产化管理。

2. 推荐目录结构

text 复制代码

/opt/wechatbot-webhook/
  docker-compose.yml
  .env
  logs/
  README-ops.md

说明：

docker-compose.yml：服务定义。
.env：敏感配置，例如 token、回调地址。
logs/：应用日志目录。
README-ops.md：记录维护信息。

3. 基础 docker-compose.yml

yaml 复制代码

services:
  wxBotWebhook:
    image: dannicool/docker-wechatbot-webhook
    container_name: wxBotWebhook
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./logs:/app/log
    environment:
      - LOG_LEVEL=info
      - LOGIN_API_TOKEN=${LOGIN_API_TOKEN}

配套 .env：

env 复制代码

LOGIN_API_TOKEN=change_this_to_a_random_token

启动：

bash 复制代码

docker compose up -d

查看日志：

bash 复制代码

docker compose logs -f

4. 接收消息场景配置

如果需要把收到的微信消息转发到业务系统，增加 RECVD_MSG_API。

yaml 复制代码

services:
  wxBotWebhook:
    image: dannicool/docker-wechatbot-webhook
    container_name: wxBotWebhook
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./logs:/app/log
    environment:
      - LOG_LEVEL=info
      - LOGIN_API_TOKEN=${LOGIN_API_TOKEN}
      - RECVD_MSG_API=${RECVD_MSG_API}
      - ACCEPT_RECVD_MSG_MYSELF=false

.env：

env 复制代码

LOGIN_API_TOKEN=change_this_to_a_random_token
RECVD_MSG_API=https://example.com/wechat/receiver

5. 更安全的本机监听配置

如果服务前面有 Nginx 或 Caddy，建议只监听 127.0.0.1。

yaml 复制代码

services:
  wxBotWebhook:
    image: dannicool/docker-wechatbot-webhook
    container_name: wxBotWebhook
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./logs:/app/log
    environment:
      - LOG_LEVEL=info
      - LOGIN_API_TOKEN=${LOGIN_API_TOKEN}
      - RECVD_MSG_API=${RECVD_MSG_API}
      - ACCEPT_RECVD_MSG_MYSELF=false

这样外部无法直接通过服务器 IP 访问 3001，只能通过反向代理入口访问。

6. 环境变量说明

变量	示例	说明
`LOG_LEVEL`	`info`	控制控制台输出日志级别
`RECVD_MSG_API`	`https://example.com/receiver`	收到微信消息后回调的业务接口
`ACCEPT_RECVD_MSG_MYSELF`	`false`	是否把自己发出的消息也上报
`LOGIN_API_TOKEN`	`random_token`	登录和接口鉴权 token
`DISABLE_AUTO_LOGIN`	`true`	是否禁用自动登录，每次启动都重新扫码

生产建议：

LOGIN_API_TOKEN 必须显式配置。
ACCEPT_RECVD_MSG_MYSELF 默认保持 false。
LOG_LEVEL 正常使用 info，排障时临时改 debug。
DISABLE_AUTO_LOGIN 一般不配置，除非明确需要每次扫码。

7. 启动、停止与重启

启动：

bash 复制代码

docker compose up -d

查看容器：

bash 复制代码

docker compose ps

查看日志：

bash 复制代码

docker compose logs -f

重启：

bash 复制代码

docker compose restart

停止：

bash 复制代码

docker compose down

注意：docker compose down 会删除容器，但不会删除 logs/ 目录。

8. 扫码登录流程

启动后执行：

bash 复制代码

docker compose logs -f

找到登录 URL：

text 复制代码

http://localhost:3001/login?token=YOUR_TOKEN

如果部署在服务器，替换为：

text 复制代码

http://服务器IP:3001/login?token=YOUR_TOKEN

如果使用反向代理：

text 复制代码

https://wxbot.example.com/login?token=YOUR_TOKEN

扫码成功后，访问健康检查：

bash 复制代码

curl 'http://127.0.0.1:3001/healthz?token=YOUR_TOKEN'

返回 healthy 表示微信登录态有效。

9. 反向代理建议

Nginx 示例：

nginx 复制代码

server {
    listen 443 ssl;
    server_name wxbot.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;
    }
}

进一步建议：

/login 只允许管理员 IP。
/resouces 不对公网开放，除非确有需要。
/webhook/msg/v2 增加 Basic Auth 或网关鉴权。
所有外部访问使用 HTTPS。

10. 健康检查脚本

可以写一个简单脚本定时检测：

bash 复制代码

#!/usr/bin/env bash

TOKEN="change_this_to_a_random_token"
URL="http://127.0.0.1:3001/healthz?token=${TOKEN}"

STATUS=$(curl -fsS "$URL" || true)

if [ "$STATUS" != "healthy" ]; then
  echo "wechatbot-webhook is unhealthy: $STATUS"
  exit 1
fi

echo "wechatbot-webhook is healthy"

注意：容器存活不代表微信在线，必须检查 /healthz。

11. 更新流程

bash 复制代码

docker compose pull
docker compose down
docker compose up -d
docker compose logs -f

由于项目已经归档，更新前建议：

记录当前镜像版本或 digest。
先在测试环境验证登录和发消息。
确认接口行为没有变化。
保留回滚方案。

12. 生产化检查清单

使用 docker-compose.yml 管理服务。
配置 restart: unless-stopped。
固定 LOGIN_API_TOKEN。
日志挂载到宿主机。
不直接公网暴露 3001。
使用 HTTPS 反向代理。
配置 /healthz 监控。
保留掉线告警方式。
机器人账号不是个人主力账号。
不用于高频群发。

13. 推荐最终配置

yaml 复制代码

services:
  wxBotWebhook:
    image: dannicool/docker-wechatbot-webhook
    container_name: wxBotWebhook
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./logs:/app/log
    environment:
      - LOG_LEVEL=info
      - LOGIN_API_TOKEN=${LOGIN_API_TOKEN}
      - RECVD_MSG_API=${RECVD_MSG_API}
      - ACCEPT_RECVD_MSG_MYSELF=false

.env：

env 复制代码

LOGIN_API_TOKEN=replace_with_strong_random_token
RECVD_MSG_API=https://example.com/wechat/receiver

如果只发送消息，不接收消息，可以删除 RECVD_MSG_API。