Repository navigation
Deployment Guide
BlueSkyXN edited this page May 4, 2026
·
4 revisions
事实来源：主仓
pr-88@a312645的Dockerfile、docker-compose.yml、entrypoint.sh、scripts/warp-init.sh、cloud/hfs/、cloud/modelscope/，以及主仓docs/hf-space-cd.md。
从开发机到生产的部署路径。本页只讲怎么部署；网络层和安全配置见 Network and WARP 与 Authentication and Roles。
flowchart TD
Q[部署目标？]
Q --> Local[本机 / 内网]
Q --> Pub[公网]
Q --> Cloud[Serverless / 托管]
Local --> D1[Docker compose] & D2[souwen serve + systemd]
Pub --> D3[Docker compose + Nginx/Caddy + TLS] & D4[K8s + Ingress]
Cloud --> D5[HuggingFace Spaces] & D6[ModelScope]
services:
souwen:
image: ghcr.io/blueskyxn/souwen:latest # 或自构建
ports:
- "49265:49265"
env_file: [.env]
environment:
- SOUWEN_ADMIN_PASSWORD=${SOUWEN_ADMIN_PASSWORD}
- SOUWEN_USER_PASSWORD=${SOUWEN_USER_PASSWORD}
- SOUWEN_TRUSTED_PROXIES=10.0.0.0/8,127.0.0.1
- SOUWEN_EXPOSE_DOCS=false
volumes:
- souwen-data:/app/data
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:49265/health"]
interval: 30s
timeout: 5s
start_period: 30s
retries: 3
volumes:
souwen-data:启动 / 日志 / 关停：
docker compose up -d
docker compose logs -f souwen
docker compose down主仓 Dockerfile 三阶段：
-
microsocks-builder（Alpine + make） -
panel-builder（node:22-slim + Vite，ARGSKINS=all或单皮肤减小体积） - 运行时（
python:3.11-slim+ 预装 wgcf/wireproxy/usque/microsocks/wireguard-tools）
# 全皮肤
docker build -t souwen .
# 单皮肤（更小）
docker build --build-arg SKINS=souwen-google -t souwen .
# 自定义 WARP 组件版本
docker build --build-arg WGCF_VERSION=2.2.30 --build-arg WIREPROXY_VERSION=1.1.2 -t souwen .
# 包含 web2pdf 插件 + Playwright Chromium
docker build --build-arg WITH_WEB2PDF=1 -t souwen-with-web2pdf .加到 docker-compose.yml 的 souwen service：
environment:
- WARP_ENABLED=1
- WARP_MODE=auto # auto / wireproxy / kernel / usque / warp-cli / external
- WARP_SOCKS_PORT=1080
- WARP_HTTP_PORT=0 # 0=不启用 HTTP 代理
# external 模式
# - WARP_EXTERNAL_PROXY=socks5://warp:1080
# kernel 模式必须
cap_add: [NET_ADMIN]
devices: [/dev/net/tun:/dev/net/tun]
sysctls: ["net.ipv4.conf.all.src_valid_mark=1"]详见 Network and WARP。
不要把 Key 写进 compose 文件。三种推荐：
# 1. .env（git ignore）
env_file: [.env]
# 2. Docker swarm / K8s secrets
environment:
SOUWEN_ADMIN_PASSWORD_FILE: /run/secrets/admin_pwd
secrets:
admin_pwd:
file: ./secrets/admin_pwd
# 3. 启动前注入（Vault / SOPS）
docker compose run -e SOUWEN_TAVILY_API_KEY=$(vault kv get -field=tavily secret/souwen) souwen参考 cloud/hfs/：
cp -r cloud/hfs ~/my-souwen-space
cd ~/my-souwen-space
git init && git remote add origin https://huggingface.co/spaces/<your>/<name>
git add . && git commit -m "init"
git push -u origin main关键差异（与主仓 Dockerfile 相比）：
- HF Spaces 监听 7860（Spaces 默认端口）。
- 通常只装
[server,tls]，不装[crawl4ai]（资源限制）。 -
SOUWEN_ADMIN_PASSWORD在 Space Settings → Variables and secrets。
完整 CD / 验收流程见主仓 docs/hf-space-cd.md。
参考 cloud/modelscope/。结构与 HF Spaces 类似，区别在于配置文件名（README.md 头部 frontmatter）和默认端口。
upstream souwen { server 127.0.0.1:49265; }
server {
listen 443 ssl http2;
server_name souwen.example.com;
ssl_certificate /etc/letsencrypt/live/souwen.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/souwen.example.com/privkey.pem;
# 关键：SouWen 用 X-Forwarded-For 解析真实 IP（须配 trusted_proxies）
location / {
proxy_pass http://souwen;
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; # LLM 摘要可能慢
}
# SSE / WARP events
location /api/v1/admin/warp/events {
proxy_pass http://souwen;
proxy_buffering off;
proxy_cache off;
proxy_set_header Connection '';
proxy_http_version 1.1;
chunked_transfer_encoding off;
}
}SouWen 端：
trusted_proxies:
- 127.0.0.1 # 反代在本机
- 10.0.0.0/8 # K8s/swarm 内网
expose_docs: false # 生产建议souwen.example.com {
reverse_proxy 127.0.0.1:49265 {
flush_interval -1
header_up X-Real-IP {remote_host}
}
}apiVersion: apps/v1
kind: Deployment
metadata: { name: souwen }
spec:
replicas: 2
selector: { matchLabels: { app: souwen } }
template:
metadata: { labels: { app: souwen } }
spec:
containers:
- name: souwen
image: ghcr.io/blueskyxn/souwen:latest
ports: [{ containerPort: 49265 }]
envFrom:
- secretRef: { name: souwen-secrets }
livenessProbe:
httpGet: { path: /health, port: 49265 }
periodSeconds: 30
readinessProbe:
httpGet: { path: /readiness, port: 49265 }
periodSeconds: 10
volumeMounts:
- { name: data, mountPath: /app/data }
volumes:
- name: data
persistentVolumeClaim: { claimName: souwen-data }
---
apiVersion: v1
kind: Service
metadata: { name: souwen }
spec:
selector: { app: souwen }
ports: [{ port: 80, targetPort: 49265 }]
---
apiVersion: v1
kind: Secret
metadata: { name: souwen-secrets }
stringData:
SOUWEN_ADMIN_PASSWORD: change-me
SOUWEN_TRUSTED_PROXIES: "10.0.0.0/8"多副本时注意：搜索限流是每进程内存滑动窗口。要全局限流，改 Ingress / API Gateway 层做。
# 改环境变量后
docker compose up -d --force-recreate souwen
# 或不重启，调 reload（已运行进程）
curl -X POST -H "Authorization: Bearer $ADMIN_PWD" \
http://localhost:49265/api/v1/admin/config/reloadYAML 改动要么重启，要么 reload；env 改动只能重启生效。
| 指标 | 来源 |
|---|---|
| 服务可用 |
GET /health（liveness） |
| 数据源就绪 | GET /readiness |
| 数据源健康 | GET /api/v1/admin/doctor |
| WARP 状态 | GET /api/v1/admin/warp |
| 错误码分布 | 日志中按 error 字段聚合 |
可结合 Prometheus / Grafana / Loki 做仪表盘；SouWen 当前没内置 Prometheus metrics，可以反向代理层加 nginx_exporter。
# 升级
docker compose pull
docker compose up -d
# 回滚（用 tag 锁定版本）
docker compose --env-file .env.v1.1.0 up -d升级前看 CHANGELOG 的 "Behavior" 段，特别注意 admin/auth/registry 不兼容变更。
- Network and WARP — 出口网络配置
- Authentication and Roles — 三角色 + trusted_proxies
- Web Panel — 部署后用什么管理
- Troubleshooting — 部署常见问题
Last calibrated：2026-05-04 · 主仓 pr-88 @ a312645`
Home · Quick Start · Architecture · FAQ · Troubleshooting · Coverage Manifest · Contributing
权威技术文档以主仓 docs/ 与 src/ 为准。本项目仅供 Python 学习与技术研究使用，禁止用于违反法律法规或第三方服务条款的用途。