94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# AdCloud Server
|
||
|
||
面向开发者和 coding agent 的广告云埋点与广告推送后端。使用 FastAPI 开发，依赖和虚拟环境统一由 **uv** 管理。
|
||
|
||
## HTTP Gateway
|
||
|
||
```text
|
||
HTTPS :443 (Nginx，终止 TLS)
|
||
├── /v1/events/* → events 路由模块
|
||
├── /v1/users/* → users 路由模块
|
||
├── /v1/ads/* → ads 路由模块
|
||
├── /v1/identity/* → identity 路由模块
|
||
└── /v1/... → 后续业务模块
|
||
↓
|
||
FastAPI 127.0.0.1:8000
|
||
```
|
||
|
||
目前使用模块化单体：四个业务模块共用一个 FastAPI 进程和版本入口。
|
||
Nginx 为各业务域定义了独立 upstream，后续拆分服务时可以替换地址。
|
||
Gateway 保留完整路径和查询参数，不剥离 `/v1` 或业务前缀。
|
||
未知路径返回 404，不支持的 HTTP 方法返回 405。
|
||
|
||
| 路径 | 模块职责 | 当前已实现接口 |
|
||
| --- | --- | --- |
|
||
| `/v1/events/*` | 埋点事件接收与查询 | `GET /v1/events/health` |
|
||
| `/v1/users/*` | 平台用户资料管理 | `GET /v1/users/health` |
|
||
| `/v1/ads/*` | 广告管理与投放 | `GET /v1/ads/health` |
|
||
| `/v1/identity/*` | 登录、令牌与身份权限 | `GET /v1/identity/health` |
|
||
|
||
各模块健康接口用于验证路由挂载，返回 `{"status":"ok","module":"events"}` 等响应；不代表数据库或外部依赖已就绪。
|
||
当前阶段仅实现 Gateway 和模块入口，尚未实现业务写入、数据持久化、登录或鉴权。
|
||
|
||
```text
|
||
src/adcloud_server/
|
||
main.py # 应用工厂、CORS、系统健康接口
|
||
schemas.py # 公共响应模型
|
||
api/v1/router.py # /v1 统一入口和模块注册
|
||
api/v1/events.py
|
||
api/v1/users.py
|
||
api/v1/ads.py
|
||
api/v1/identity.py
|
||
```
|
||
|
||
增加新模块时，在 `api/v1/` 新增 `APIRouter`，并在 `router.py` 中注册前缀和 OpenAPI 标签。
|
||
若部署为独立服务，再增加对应的 Gateway upstream 和 location。
|
||
|
||
## 本地开发
|
||
|
||
```sh
|
||
uv sync --locked
|
||
uv run uvicorn adcloud_server.main:app --reload --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
- 系统健康检查：`http://localhost:8000/health`（保留 SDK 和控制台兼容）
|
||
- 模块探测：`http://localhost:8000/v1/events/health`
|
||
- API 文档：`http://localhost:8000/docs`
|
||
- OpenAPI：`http://localhost:8000/openapi.json`
|
||
|
||
默认允许来自 `http://localhost:3000`、`http://localhost:5173`、`http://localhost:5174` 的浏览器请求。
|
||
`CORS_ORIGINS` 接受逗号分隔的来源；环境配置示例见 `.env.example`。
|
||
|
||
```sh
|
||
CORS_ORIGINS=https://advertiser.example,https://developer.example uv run uvicorn adcloud_server.main:app
|
||
```
|
||
|
||
CORS 已配置写请求方法和 `Authorization`、`Content-Type`、`X-Request-ID` 请求头。
|
||
允许预检不代表相应业务端点已实现；CORS 也不代替身份认证和权限校验。
|
||
|
||
## HTTPS 入口配置
|
||
|
||
`deploy/nginx.conf.example` 是放入 Nginx `http {}` 上下文的配置模板。
|
||
替换 `server_name` 和证书文件路径，然后在目标服务器使用 `nginx -t` 检查，加载配置。
|
||
模板未在本机启动 443，也未申请或部署证书。API 文档仅通过内部 FastAPI 地址访问。
|
||
|
||
Nginx 在公网边缘重写转发头，FastAPI 只监听回环地址。目标服务器启动后端：
|
||
|
||
```sh
|
||
uv run uvicorn adcloud_server.main:app --host 127.0.0.1 --port 8000 --proxy-headers --forwarded-allow-ips 127.0.0.1
|
||
```
|
||
|
||
模板允许最大 1 MiB 请求体，连接超时 5 秒、读写超时 30 秒；可按后续埋点批量策略调整。
|
||
|
||
参考：[FastAPI 多模块路由](https://fastapi.tiangolo.com/tutorial/bigger-applications/)、[Nginx proxy_pass 路径规则](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass)。
|
||
|
||
## 检查
|
||
|
||
```sh
|
||
uv run pytest
|
||
uv run ruff check .
|
||
uv run ruff format --check .
|
||
```
|
||
|
||
提交 `uv.lock`，使用 `uv sync --locked` 复现依赖。
|