WeChat-AI/docs/docker.md

Docker ?¨ç½²

?�ç½®?¡ä»¶

ä¾�è?	说æ?
Docker + Compose	?¬æœº?–æ??¡å™¨å·²å?è£?
Upstash Redis	.env �REDIS_URL=rediss://...
LINUX DO OAuth	Client ID/Secret + ?¬ç??žè??°å?
å¹³å�° LLM（主站直连ï?	LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
工具网关（用?·è‡ªå®šä? API + ?œç´¢ï¼?	TOOLS_BASE_URL / TOOLS_API_KEYï¼›é??�è? huggingface/wechat-ai-tools

快速�??

cd /path/to/WeChat-AI

# ?�ç½®?¯å??˜é?（勿?�交 .envï¼?# ?Ÿäº§?¡å?修改ï¼?#   PUBLIC_BASE_URL=https://ä½ ç??Ÿå?
#   LINUXDO_REDIRECT_URI=https://ä½ ç??Ÿå?/api/v1/auth/callback
#   REDIS_URL / LLM_* / LINUXDO_CLIENT_*
# ?¨æˆ·?ªå?ä¹?API + ?œç´¢ï¼šTOOLS_BASE_URL / TOOLS_API_KEY
#   docker compose --profile tools up -d --build
#   TOOLS_BASE_URL=http://wechat-ai-tools:7860

# ?¨è?：å???+ ??OTA ??+ ?„建（æ??€ Cookieï¼?pnpm docker:up
# ?ªå?义é??�å?ï¼?pnpm docker:build -- -- docker build -t your-dockerhub-user/wechat-ai:latest .

# ?…在 dist/release/<?ˆæœ¬>/files.json
# æµ�è??¨ç™»å½?/admin ???¨ç½²?‚点 ?’「ä?传通é??…ã€�â? ?�点?‚点?Œæ›´?°ã€?
docker compose logs -f wechat-ai

?•ç‹¬?„建 tools ?œå?

docker build -t wechat-ai-tools:latest -f huggingface/wechat-ai-tools/Dockerfile huggingface/wechat-ai-tools
docker run --rm -p 7860:7860 -e TOOLS_API_KEY=secret -e ALLOW_REQUEST_UPSTREAM=true wechat-ai-tools:latest

详è? docs/ai-gateway.md?�huggingface/wechat-ai-tools/README.md??

?ˆæœ¬ä¸Žé€šé?ï¼? pnpm docker:build 默认：å??????¬åœ° pack* ??Docker?? ?šé??‘å??ªèµ°ç½‘页：/admin ??上ä? files.json（æ? CLI Cookie）ã€? ?´æŽ¥è·?docker build ä¸�ä??‡ç??�ä?ä¸�ä??“通é??…ã€?

?°å?	说æ?
/	?Ÿèƒ½ä»‹ç??½åœ°é¡µï?OG ?†äº«??/og.jpgï¼?
/app	?¨æˆ·ä¸­å?（LINUX DO ?»å??�å??ºå™¨äººï?
/admin	管ç??Žå�°ï¼ˆä»ªè¡¨ç? / Tokenï¼?
/health	?¥åº·æ£€??

仅用 Dockerfile

# ?‡ç? + docker build -t wechat-ai .
pnpm docker:build -- --raw
# ?–自定ä?：node scripts/docker-build.mjs -- docker build -t wechat-ai:0.2.1 .

docker run -d --name wechat-ai --restart unless-stopped \
  --env-file .env \
  -e WECHAT_AI_HOST=0.0.0.0 \
  -e WECHAT_AI_PORT=8787 \
  -p 8787:8787 \
  wechat-ai

Bot token 与表?…å??‡å? Redis（ä? REDIS_URL ?Œå?）ï?容器?�建ä¸�丢；æ??€?¬åœ°?°æ�®?·ã€?

?Ÿäº§?¯å?检?¥æ???

1. LINUX DO 应用?žè?ä¸?.env 完全一?´ï?
   https://ä½ ç??Ÿå?/api/v1/auth/callback
2. PUBLIC_BASE_URL = https://ä½ ç??Ÿå?（æ?å°¾æ?? ï?
3. HTTPS ?¶è®¾ç½?COOKIE_SECURE=true
4. Redis 使用 Upstash rediss://，æ??¡å™¨?½è®¿?®å?ç½?5. Bot token å·²å???Redis（ä? REDIS_URL ?Œå?）ï??�建容器ä¸�ä?丢登å½?

常用?½ä»¤

docker compose ps
docker compose logs -f
docker compose restart
docker compose down          # ?œæ??¡ï?Bot token ??Redis，ä??—å½±?�ï?
docker compose down -v       # ??down（本?�务? æ?ä¹…å? volumeï¼?pnpm docker:up                                # ?‡ç?+?¬åœ° pack+compose up --build
pnpm docker:build -- -- docker build -t your-dockerhub-user/wechat-ai:latest .
# ?¶å? /admin ??上ä??šé???(files.json) ???´æ–°?‚点
pnpm docker:build -- --no-channel             # ?ªå??ˆæ?建ï?ä¸?pack

OTA 增é??´æ–°ï¼ˆå??‚点?¥å¸¸?­ä¿®ï¼?

业务æº�ç?å°�改?¯ä?å¿…æ???docker build：本??pack ??管ç??Žå�°ä¸Šä??šé?????对è�½?Žè??¹ç‚¹?Œæ›´?°ã€�ã€?

# ?„建顺带?“通é???pnpm docker:build -- -- docker build -t your-dockerhub-user/wechat-ai:latest .
# ?–ä? packï¼?pnpm release:pack

# æµ�è???/admin ???¨ç½²?‚点 ?’「ä?传通é??…ã€�é€?dist/release/<ver>/files.json
# ?’「更?°å…¨?¨è�½?Žã€?```

| é¡?| 说æ? |
|----|------|
| å·®é? | ?‰æ?ä»?sha256 比对，å�ªä¸‹å??˜æ›´?‡ä»¶ |
| ?�å�¯ | ?‚点 `process.exit(0)`，ä?èµ?`restart: unless-stopped` ?‰èµ·**?Œä?容器**（å�¯?™å?ä¿�ç?è¡¥ä?ï¼?|
| ?ˆæœ¬ | 心跳 `version`：`.wa-version`（OTA ?™å…¥ï¼‰â? `APP_VERSION` ????`package.json` |
| ä»�é??œå? | Node ?ºç??œå??�系统å??�Dockerfile?�`OTA_ALLOW_INSTALL=false` ?¶ç?ä¾�è?大å? |

?¯å??˜é?：`OTA_ENABLED`（é?è®?true）ã€�`OTA_ALLOW_INSTALL`?�`APP_VERSION`（æ? OTA ?³æ—¶?¯é€‰ï??�`OTA_STAGING_DIR`?? 
**注æ?ï¼?* OTA ?ªæ”¹?‡ä»¶?�ä??¹çŽ¯å¢ƒå??�ï??ˆæœ¬??`/app/.wa-version` 上报，æ??€?�ä?ä¸�å???`APP_VERSION` è·Ÿç??? 
`docker compose up --build` / ?�建容器会丢?‰ä???OTA ?™å…¥?„è¡¥ä¸�ï??¿æ?ä»�以?œå?ä¸?source of truth??
## ?�代示ä?

?Ÿäº§?¨è??Šå??�æ???**Cloudflare**（æ?云代??+ Cache Rules）ï?è§?**`docs/cloudflare.md`**（Business 缓å?规å??�忽??Cookie?�Purge 清å?）ã€?
### Caddy（æ? CF ?¶ï?

```caddy
your.domain.com {
  reverse_proxy 127.0.0.1:8787
}

Nginx（æ? CF ?¶ï???CF ??Nginx ??Nodeï¼?

server {
  listen 443 ssl;
  server_name your.domain.com;
  # ssl_certificate ...;

  location / {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    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;
    # Cloudflare 还å??Ÿå? IP ?¶å�¯?¨ï?
    # proxy_set_header CF-Connecting-IP $http_cf_connecting_ip;
  }
}

æº�ç?å·²è???Cache-Control / Cloudflare-CDN-Cache-Control?�HTML ETag?�公开表æ? /cdn/s/:id?v=?‚å?ä»??ä¸�å??�å? proxy_cache，除?žä?ä¸�用 Cloudflare??## ?œå?说æ?

• ?ºç??œå?：node:22-bookworm-slim
• ?…管?†ï?pnpm monorepo
• ?¯åŠ¨ï¼špnpm db:seed（å?ç­‰ï???pnpm --filter @wechat-ai/api startï¼?*API + Worker ?Œè?ç¨?*ï¼?- ??root ?¨æˆ· appuser è¿�è?
• ?¥åº·æ£€?¥ï?GET /health

Worker 规模（å??œå?ï¼?

默认ä»�是 **一个容?¨è??¨éƒ¨**：HTTP + iLink ?¿è½®è¯?+ AI ?žå???

?¯å??˜é?	默认	说æ?
MAX_BOTS_PER_WORKER	500	?¬è?程æ?多å???long-poll ??bot ??
REPLY_CONCURRENCY	16	?Œæ—¶è¿›è???LLM/?‘é€�ä»»?¡æ•°
LEASE_TTL_SEC	45	租约 TTL（å??œå?多副?¬æ—¶?²é?å¤?pollï¼?

?ºå™¨äººå?多时优å?è°ƒé? MAX_BOTS_PER_WORKER 与系ç»?ulimit -n（注?�å?å­˜ä??ºç?连接?°ï??? 默认 *?•å‰¯?¬ä?体部ç½? ?³å�¯ï¼›å??œå?多副?¬å·²?¯æ?（Redis 租约?†ç? poll）ã€?

多è??¹å??„部署ï?10+ ?°ï?

æ¯�å�°?�务?¨è?**?Œä??œå?**（API + Worker）ï??±ç”¨ä¸€ä¸?Upstash Redis；用?·å�ªè®¿é—®**主å???*??

应用 env（全站ä??´ï?

PUBLIC_BASE_URL=https://ä½ ç?主å???LINUXDO_REDIRECT_URI=https://ä½ ç?主å???api/v1/auth/callback
REDIS_URL=rediss://...
COOKIE_SECURE=true
WORKER_ENABLED=true

æ¯�è??¹ä???

WORKER_ID=node-01          # 必填且唯一
NODE_LABEL=cn-east-1a      # ?¯é€‰ï?管ç??Žå�°å±•ç¤º
NODE_REGION=cn-east        # ?¯é€?```

**ä¸�è?**ç»™æ??°è®¾ä¸�å???`PUBLIC_BASE_URL`?‚æ?站直连地?€ï¼ˆIP:8787）å�ª?™åœ¨ Cloudflare Worker ??`ORIGINS`，è? `cloudflare-worker/README.md`??
### ?¨ç½²æ­¥éª¤?˜è?

1. ?„机：`docker run ... --env-file .env -e WORKER_ID=node-0N -p 8787:8787 wechat-ai`  
2. ?�置并部�`cloudflare-worker`，`ORIGINS=http://ip1:8787,http://ip2:8787,...`  
3. 主å??�ç???Worker  
4. ?“å? `/admin` ??**?‚点**：å??‹åˆ°??`WORKER_ID` 心跳与ç?çº?bot ?? 

| ?¢æ´» | è·¯å? |
|------|------|
| Docker / è½»é? | `GET /health` |
| LB 就绪（� Redis�| `GET /health/ready` |

管ç? API：`GET /api/v1/admin/nodes`（Cookie 管ç??˜ï???
?«ç?? æœº?¨äººä¼šè??¶æ€�在 Redis，HTTP ? é?粘性ä?è¯�ã€?
### 租约?ªåŠ¨?�平衡ï?rebalanceï¼?
多è??¹é?è®?**å¼€??*：ç?约å?多ç?è¿›ç?会周?Ÿæ€?**主动?Šæ”¾** 多ä? lease（ä? pause bot）ï?空闲?‚点下ä?è½?`claim` ?¡èµ°ï¼Œä½¿?„è???bot ?°æŽ¥è¿‘å??†ã€?
| ?¯å??˜é? | 默认 | 说æ? |
|----------|------|------|
| `REBALANCE_ENABLED` | `true` | 设为 `false` ?³é—­ï¼ˆç?约ç??¨é?? è??¹ï? |
| `REBALANCE_INTERVAL_SEC` | `60` | ?Œä?è¿›ç?两次 shed ?€å°�é—´??|
| `REBALANCE_SLACK` | `2` | ?�许高出?‡å?多å?个å??Šæ”¾ |
| `REBALANCE_MAX_PER_TICK` | `50` | æ¯�次?€å¤šé??¾æ•°ï¼ˆé�¿?�瞬?´ç©ºçª—è?大ï? |

?¥å??³é”®å­—ï?`[worker] rebalance shed N bot(s)`?‚约 `ceil(超é? / 50)` ?†é??…收?›ã€?
### 强制下线?‚点

管ç??Žå�° **?‚点** é¡???**强制下线**ï¼?
1. ?™å…¥ Redis fence（`wa:worker:{id}:fence`ï¼? 
2. ?Šæ”¾è¯?WORKER_ID 下全??bot 租约  
3. �`wa:workers:reg` 移除  

?®æ?è¿›ç?下ä?è½?reconcile ?‘现 fence ?Žå?止认领ï??¶ä??‚点 claim è¿™ä? bot?? 
**è§?™¤ä¸‹çº¿** ?Žè¯¥?‚点?¯é??°å??¥ã€? 

è¿?*ä¸�ä?** `docker stop`；若è¦�ä? LB ?˜æ??�ï?还è?ä»?Cloudflare Worker `ORIGINS` ?»æ?该æ?ç«™ã€