# 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` |


## 快速启??
```bash
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 ?��?

```bash
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

```bash
# ?��? + 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` ?��?）�??�建容器不�?丢登�?
## 常用?�令

```bash
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 ??管�??�台上�??��?????对落?��??�点?�更?�」�?
```bash
# ?�建顺带?�通�???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�?
```nginx
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（全站�??��?

```env
PUBLIC_BASE_URL=https://你�?主�???LINUXDO_REDIRECT_URI=https://你�?主�???api/v1/auth/callback
REDIS_URL=rediss://...
COOKIE_SECURE=true
WORKER_ENABLED=true
```

### 每�??��???
```env
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` ?��?该�?站�