Tutorial Production

Tutorial 03 · 部署到生产

学习目标：把 SouWen 部署成一个有认证、限流、TLS、监控的生产服务。 前置：Tutorial 01 跑通；有一台 Linux 服务器；域名 + DNS 可控。 耗时：约 30-45 分钟。

---

全景

flowchart LR
    User[公网用户] -->|HTTPS| Caddy[Caddy / Nginx]
    Caddy -->|HTTP :49265| SouWen[SouWen Docker]
    SouWen -->|/api/v1/admin/*| Admin[Admin 鉴权]
    SouWen -->|/api/v1/search/*| User2[User 鉴权 + 限流]
    SouWen --> Vol[(souwen-data 卷)]
    Caddy --> LE[Let's Encrypt 自动 TLS]

Loading

---

步骤 1：服务器准备

# Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# 重新登录

# 创建工作目录
mkdir -p ~/souwen && cd ~/souwen

---

步骤 2：生成强密码

ADMIN_PWD=$(openssl rand -hex 32)
USER_PWD=$(openssl rand -hex 16)

cat > .env <<EOF
SOUWEN_ADMIN_PASSWORD=$ADMIN_PWD
SOUWEN_USER_PASSWORD=$USER_PWD
SOUWEN_TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8
SOUWEN_EXPOSE_DOCS=false
SOUWEN_OPENALEX_EMAIL=you@example.com
SOUWEN_TAVILY_API_KEY=tvly-xxx
EOF

chmod 600 .env

把 $ADMIN_PWD 和 $USER_PWD 记到密码管理器。

---

步骤 3：docker-compose

# ~/souwen/docker-compose.yml
services:
  souwen:
    image: ghcr.io/blueskyxn/souwen:latest
    container_name: souwen
    ports:
      - "127.0.0.1:49265:49265"          # 仅本机暴露，让反代转发
    env_file: [.env]
    environment:
      - WARP_ENABLED=1                    # 可选：启 WARP
      - WARP_MODE=auto
    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 | head -50

预期看到 Uvicorn running on http://0.0.0.0:49265。

---

步骤 4：本地验证

curl http://127.0.0.1:49265/health
# {"status":"ok","version":"1.1.1"}

curl -H "Authorization: Bearer $ADMIN_PWD" http://127.0.0.1:49265/api/v1/admin/doctor | jq '.status_counts'

---

步骤 5：装 Caddy（自动 TLS）

# Debian/Ubuntu
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy.gpg
echo "deb [signed-by=/usr/share/keyrings/caddy.gpg] https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install -y caddy

写 /etc/caddy/Caddyfile：

souwen.example.com {
    reverse_proxy 127.0.0.1:49265 {
        flush_interval -1
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }

    log {
        output file /var/log/caddy/souwen.log
    }
}

DNS：把 souwen.example.com 的 A 记录指向你的服务器 IP。

sudo systemctl reload caddy

Caddy 会自动从 Let's Encrypt 申请证书。验证：

curl -I https://souwen.example.com/health

---

步骤 6：远程验证

# 公开端点
curl https://souwen.example.com/health

# User 端点
curl -H "Authorization: Bearer $USER_PWD" \
  https://souwen.example.com/api/v1/search/paper?q=test | jq

# Admin 端点
curl -H "Authorization: Bearer $ADMIN_PWD" \
  https://souwen.example.com/api/v1/admin/doctor | jq

不带 Token 调 admin 应该返 401（默认锁定）。

---

步骤 7：Web Panel

浏览器访问 https://souwen.example.com/panel#/。用 $ADMIN_PWD 登录。

• /dashboard 概览
• /sources 看每源状态
• /network /warp 调代理
• /plugins（部分皮肤）

---

步骤 8：监控

/etc/cron.d/souwen-health：

*/5 * * * * root curl -fs https://souwen.example.com/readiness > /dev/null || systemctl restart caddy

或更专业地接 Uptime Kuma / Prometheus blackbox_exporter / Datadog。

日志：

docker compose logs --tail 200 souwen
sudo journalctl -u caddy -n 100

---

步骤 9：升级 / 回滚

# 升级
docker compose pull
docker compose up -d
# 验证
curl https://souwen.example.com/health

# 回滚（用 tag 锁定）
sed -i 's|souwen:latest|souwen:1.1.0|' docker-compose.yml
docker compose up -d

---

安全清单（生产前必过）

• admin_password 设了强随机串
• 没有 SOUWEN_ADMIN_OPEN=1
• trusted_proxies 配了反代地址
• expose_docs=false
• cors_origins 是白名单（不是 *）
• Caddy / Nginx TLS 自动续期
• 服务端口 49265 仅 127.0.0.1 暴露，不直通公网
• .env 文件 chmod 600
• 监控 /health /readiness
• 定期 rotate admin_password

---

进阶

• 多副本：搜索限流是每进程内存；要全局限流走 API Gateway。
• K8s：见 Deployment Guide#5-K8s。
• HF Spaces / ModelScope：见 Deployment Guide#2-Hugging-Face-Spaces。
• WARP 模式选择：见 Network and WARP。

---

你学到了什么

• 生产部署 = Docker + 反代 + TLS + 鉴权 + 限流 + 探针。
• 127.0.0.1 绑定 + 反代是最低权限模式。
• Admin 默认锁定让"忘配密码就上线"也安全。
• trusted_proxies 是反代后的关键点。

---

接下来

• Deployment Guide — 详细部署模板（Nginx / K8s / HF）
• Authentication and Roles — 三角色与默认锁定细节
• Troubleshooting — 部署后常见问题