微信机器人-webhook技术文档_02-部署前准备与环境规划

微信机器人 webhook 部署前准备与环境规划

1. 部署前先确认目标

部署 wechatbot-webhook 前，先明确要解决的问题。不同目标对应的网络和安全要求不同。

常见目标：

目标	推荐部署方式	是否需要公网
本地测试发送消息	Node.js / Docker	不需要
服务器告警推送	Docker / Compose	不一定，需要看告警来源
n8n 接收微信消息	Docker Compose	通常需要平台可访问
Coze 调用发送消息	Docker Compose + 反向代理	通常需要公网
内部系统通知	Docker Compose	推荐内网
长期低频使用	Docker Compose	视场景决定

如果只是内部系统调用，建议只部署在内网，不要直接暴露公网。

2. 服务器要求

推荐环境：

Linux 服务器：Ubuntu 20.04+、Debian 11+、CentOS 7+
CPU 架构：amd64 或 arm64
内存：建议 1GB 以上
磁盘：建议预留 2GB 以上日志空间
网络：服务器可以访问外网，外部调用方可以访问机器人接口

也可以部署在：

群晖 / 绿联 / 威联通 NAS
树莓派等 ARM 设备
Windows Docker Desktop
macOS Docker Desktop

正式长期运行时，更推荐 Linux 服务器或 NAS。

3. Docker 环境准备

推荐使用 Docker 部署，因为项目镜像已经包含运行环境。

检查 Docker：

bash 复制代码

docker version

检查 Docker Compose：

bash 复制代码

docker compose version

如果系统较旧，也可能是：

bash 复制代码

docker-compose version

镜像名称：

text 复制代码

dannicool/docker-wechatbot-webhook

拉取镜像：

bash 复制代码

docker pull dannicool/docker-wechatbot-webhook

4. Node.js 环境准备

如果不用 Docker，也可以通过 npx 或全局 npm 包运行。

项目 README 提示 Node.js 版本需要：

text 复制代码

Node.js >= 18.14.1

检查版本：

bash 复制代码

node -v
npm -v

一分钟运行：

bash 复制代码

npx wechatbot-webhook

全局安装：

bash 复制代码

npm i wechatbot-webhook -g
wxbot

开发环境如果从源码运行，项目 README 提到包管理器已迁移到 pnpm，源码开发建议使用 pnpm 安装依赖。

5. 端口规划

默认服务端口：

text 复制代码

核心接口：

接口	用途
`/login?token=xxx`	获取登录二维码或查看登录状态
`/webhook/msg/v2?token=xxx`	JSON 方式发送消息
`/webhook/msg?token=xxx`	multipart 方式上传本地文件并发送
`/healthz?token=xxx`	健康检查
`/resouces?token=xxx&media=xxx`	获取头像、媒体等静态资源

端口规划建议：

本机测试：127.0.0.1:3001
内网使用：内网IP:3001
公网使用：通过 Nginx / Caddy 反向代理到 127.0.0.1:3001
不建议直接开放 3001 到公网

6. 微信账号准备

建议准备一个低风险微信账号，不建议使用个人主力账号。

原因：

Web 微信能力受微信策略限制。
登录可能失败或掉线。
高频消息可能触发风控。
项目已归档，后续兼容性无法保证。

账号建议：

使用有一定使用历史的账号。
不要使用刚注册的新号。
不要用于营销群发。
不要绑定关键业务。
开启必要的账号安全保护。

7. token 规划

项目通过 query 参数 token 做接口鉴权。

示例：

text 复制代码

http://localhost:3001/webhook/msg/v2?token=YOUR_TOKEN

如果不配置 LOGIN_API_TOKEN，项目会自动生成 token 并写入 .env 文件。生产环境建议显式配置固定 token，方便服务重启、容器迁移和自动化调用。

token 建议：

至少 16 位以上随机字符串。
不使用简单词汇，如 123456、password。
不写入公开仓库。
不出现在截图、文章、日志中。
定期更换。

示例：

bash 复制代码

-e LOGIN_API_TOKEN="change_this_to_a_random_token"

8. webhook 接收地址规划

如果需要接收微信消息，需要配置：

text 复制代码

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

该地址必须能被 wechatbot-webhook 服务访问。

常见场景：

接收方	地址要求
同一台服务器上的后端	可使用内网地址或 Docker 网络地址
n8n 云服务	需要公网 HTTPS 地址
Coze 插件服务	需要公网 HTTPS 地址
本地电脑调试	可使用内网穿透工具

生产建议：

使用 HTTPS。
接收服务也做鉴权。
校验来源或签名。
对文件类消息限制大小。
记录原始消息日志，但避免保存敏感内容。

9. 目录规划

推荐目录：

text 复制代码

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

说明：

docker-compose.yml：服务定义。
.env：token、回调地址等配置。
logs/：挂载到容器 /app/log。
README-ops.md：记录登录账号、维护人、重启方式、回调地址。

不要把 .env 提交到公开 Git 仓库。

10. 防火墙规划

如果只在本机或内网调用，不需要开放公网端口。

如果必须公网访问，建议：

云安全组只开放 80、443。
反向代理转发到本机 3001。
/login 接口只允许管理员 IP。
/webhook/msg/v2 增加额外鉴权。
禁止把 token 放在公开页面。

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;
    }
}

11. 上线前检查清单

上线前建议逐项确认：

Docker 或 Node.js 环境可用。
服务器可以访问外网。
3001 端口未被占用。
已准备非主力微信账号。
已配置强随机 LOGIN_API_TOKEN。
已决定是否需要 RECVD_MSG_API。
已配置日志目录挂载。
已规划掉线后的处理方式。
已准备替代通知通道。
已明确不用于营销群发。

12. 推荐最小生产配置

推荐使用 Docker Compose：

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=change_this_to_a_random_token
      - ACCEPT_RECVD_MSG_MYSELF=false

这个配置只监听本机 127.0.0.1，适合配合 Nginx / Caddy 使用，比直接暴露 0.0.0.0:3001 更安全。