Feature API Server

Feature: API Server

事实来源：主仓 pr-88 @ a312645 的 src/souwen/server/，依赖 [server] extra（FastAPI + Uvicorn）。

souwen serve 启动一个完整的 FastAPI 应用：61 路由 + Web Panel + OpenAPI + 三角色认证 + 限流 + ETag 缓存。

---

1. 启动方式

方式	命令 / 配置
CLI	souwen serve --host 0.0.0.0 --port 8000
Python	python -m souwen.server 或 from souwen.server import app; uvicorn.run(app)
Docker	docker run -p 49265:49265 ghcr.io/blueskyxn/souwen
K8s / Compose	详见 Deployment Guide

Docker 镜像默认监听 49265；本地 souwen serve 默认 8000。

---

2. 中间件链（按顺序）

flowchart LR
    R[Request] --> CORS[CORS]
    CORS --> XFF[trusted_proxies → X-Forwarded-For]
    XFF --> Auth[check_search_auth / require_auth]
    Auth --> Rate[rate_limit_search]
    Rate --> ID[X-Request-Id]
    ID --> H[Handler]
    H --> Err[ErrorHandler 统一 JSON]

Loading

---

3. 探针

路径	用途	行为
GET /health	容器存活	不发外网；总返 200 + {status: "ok", version}
GET /readiness	K8s readiness	仅本地检查（配置可加载 + registry 非空）

readiness 失败示例：

{ "ready": false, "version": "1.1.1", "error": "source registry is empty" }

---

4. 文档与 Panel

路径	受 expose_docs 控制	用途
GET /	否	expose_docs=true 时重定向 /docs；否则 JSON 元信息
GET /docs	是	Swagger UI
GET /redoc	是	ReDoc
GET /openapi.json	是	OpenAPI 3.1 schema
GET /panel	否	Web Panel HTML（浏览器 /panel#/ HashRouter）

/panel HTML 走内存缓存：

ETag: "<sha256-16hex>"
Cache-Control: public, max-age=3600

If-None-Match 命中返 304 Not Modified（仅头部）。支持 RFC 7232 通配符 * 与逗号分隔列表。

---

5. 关键配置

字段	默认	说明
expose_docs	true	生产建议 false
cors_origins	[]	留空 = 不启用 CORS
trusted_proxies	[]	反代后必填，否则限流失效
admin_password	null	管理端默认锁定
user_password	null	设了就保护搜索类端点
guest_enabled	false	开放无 Token 访问

详见 Authentication and Roles。

---

6. 完整路由速查

61 条路由，分为：搜索（5）/ 抓取与工具（3）/ 视频（4）/ Bilibili（4）/ Wayback（3）/ LLM（2）/ Sources（1）/ Whoami（1）/ Plugins（9 admin）/ WARP（13 admin）/ Sources Config（3 admin）/ Proxy & HTTP backend（2 admin）/ Config / Doctor / Ping（5 admin）/ 探针（4）。

完整列表见 HTTP API 与 API Reference，最终以 /openapi.json 为准。

---

7. 接下来

• HTTP API — 端点参考
• Authentication and Roles
• Web Panel
• Deployment Guide