docs(project): add production-ready documentation
Add a top-level README plus production configuration, API, and rollout documentation. Also align deployment and runbook docs with the current runtime semantics, ports, and daily pipeline entrypoints.
This commit is contained in:
phamnazage-jpg
200
docs/API_REFERENCE.md
Normal file
200
docs/API_REFERENCE.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# API 参考
|
||||
|
||||
当前服务端入口位于 `cmd/server/main.go`，只暴露只读查询接口与健康检查接口。
|
||||
|
||||
## 通用约定
|
||||
|
||||
- 基础地址：`http://<host>:<port>`
|
||||
- 默认端口：`8080`
|
||||
- 返回格式：成功接口统一返回 `{ "data": ... }`
|
||||
- 失败格式：当前直接返回纯文本错误信息，不是统一 JSON 错误结构
|
||||
- 鉴权：当前仓库未内建认证、鉴权与限流；公网暴露前应由网关或反向代理补齐
|
||||
|
||||
## `GET /health`
|
||||
|
||||
检查数据库连通性。
|
||||
|
||||
### 成功
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
### 失败
|
||||
|
||||
- `503 database not configured`：未配置 `DATABASE_URL`
|
||||
- `503 database unavailable`：数据库 Ping 失败
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8080/health
|
||||
```
|
||||
|
||||
## `GET /api/v1/models`
|
||||
|
||||
返回模型列表，数据来源于 `models`、`model_provider`、`region_pricing` 当前最新价格快照。
|
||||
|
||||
### 返回体
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": "openai/gpt-4o",
|
||||
"name": "gpt-4o",
|
||||
"provider": "OpenAI",
|
||||
"providerCN": "OpenAI",
|
||||
"modality": "text",
|
||||
"contextLength": 128000,
|
||||
"inputPrice": 2.5,
|
||||
"outputPrice": 10,
|
||||
"currency": "USD",
|
||||
"isFree": false,
|
||||
"stale": false,
|
||||
"dataConfidence": "official"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `id` | 模型外部 ID，通常是 `provider/model` |
|
||||
| `name` | 模型名称；为空时回退为 `external_id` |
|
||||
| `provider` | 英文厂商名 |
|
||||
| `providerCN` | 中文厂商名；缺失时回退为英文名或 `external_id` 前缀 |
|
||||
| `modality` | 模态类型 |
|
||||
| `contextLength` | 上下文窗口 |
|
||||
| `inputPrice` | 输入价格，单位与 `currency` 配套，默认按每百万 token |
|
||||
| `outputPrice` | 输出价格 |
|
||||
| `currency` | 币种 |
|
||||
| `isFree` | 是否免费 |
|
||||
| `stale` | 是否陈旧数据，当前由 `dataConfidence == "stale"` 推导 |
|
||||
| `dataConfidence` | 数据置信度 |
|
||||
|
||||
### 失败
|
||||
|
||||
- `503 database not configured`
|
||||
- `500 query failed`
|
||||
|
||||
## `GET /api/v1/subscription-plans`
|
||||
|
||||
返回订阅型套餐列表，当前主要对应腾讯云套餐数据。
|
||||
|
||||
### 返回体
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"planFamily": "token_plan",
|
||||
"planCode": "token-plan-lite",
|
||||
"planName": "通用 Token Plan Lite",
|
||||
"tier": "Lite",
|
||||
"provider": "Tencent",
|
||||
"providerCN": "腾讯",
|
||||
"operator": "Tencent Cloud",
|
||||
"operatorCN": "腾讯云",
|
||||
"currency": "CNY",
|
||||
"listPrice": 39,
|
||||
"priceUnit": "CNY/month",
|
||||
"quotaValue": 35000000,
|
||||
"quotaUnit": "tokens/month",
|
||||
"contextWindow": 0,
|
||||
"modelScope": ["tc-code-latest", "glm-5", "glm-5.1"],
|
||||
"sourceUrl": "https://cloud.tencent.com/document/product/1823/130060",
|
||||
"publishedAt": "2026-04-27T00:00:00",
|
||||
"effectiveDate": "2026-04-27"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 失败
|
||||
|
||||
- `503 database not configured`
|
||||
- `500 query failed`
|
||||
|
||||
## `GET /api/v1/reports/latest`
|
||||
|
||||
返回最新“正式日报”元数据。查询条件来自 `daily_report`：
|
||||
|
||||
- `status = 'generated'`
|
||||
- `output_path` 非空
|
||||
- `is_official_daily = true`
|
||||
|
||||
### 返回体
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"reportDate": "2026-05-13",
|
||||
"status": "generated",
|
||||
"modelCount": 504,
|
||||
"summaryMD": "runtime_audit ...",
|
||||
"markdownPath": "reports/daily/daily_report_2026-05-13.md",
|
||||
"htmlPath": "reports/daily/html/daily_report_2026-05-13.html",
|
||||
"archiveMarkdownPath": "reports/daily/2026/05/daily_report_2026-05-13.md",
|
||||
"archiveHtmlPath": "reports/daily/2026/05/daily_report_2026-05-13.html",
|
||||
"markdownUrl": "/api/v1/reports/latest/markdown",
|
||||
"htmlUrl": "/api/v1/reports/latest/html",
|
||||
"updatedAt": "2026-05-13T08:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 失败
|
||||
|
||||
- `503 database not configured`
|
||||
- `404 latest report not found`
|
||||
- `500 query failed`
|
||||
|
||||
## `GET /api/v1/reports/latest/markdown`
|
||||
|
||||
直接返回最新正式日报的 Markdown 文件内容。
|
||||
|
||||
### 成功
|
||||
|
||||
- `200`
|
||||
- `Content-Type: text/markdown; charset=utf-8`
|
||||
|
||||
### 失败
|
||||
|
||||
- `404 latest report not found`：数据库中没有符合条件的正式日报
|
||||
- `404 report artifact not found`：元数据存在，但落盘文件缺失
|
||||
|
||||
## `GET /api/v1/reports/latest/html`
|
||||
|
||||
直接返回最新正式日报 HTML 文件内容。
|
||||
|
||||
### 成功
|
||||
|
||||
- `200`
|
||||
- `Content-Type: text/html; charset=utf-8`
|
||||
|
||||
### 失败
|
||||
|
||||
- `404 latest report not found`
|
||||
- `404 report artifact not found`
|
||||
|
||||
## 冒烟检查命令
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8080/health
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/models | jq '.data | length'
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/subscription-plans | jq '.data | length'
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest | jq '.data.reportDate'
|
||||
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest/html > /tmp/latest_report.html
|
||||
```
|
||||
|
||||
## 生产暴露建议
|
||||
|
||||
- 在 Nginx / 网关上补齐访问控制、速率限制和超时配置
|
||||
- `/health` 仅暴露给负载均衡器和监控系统
|
||||
- 如果前端与 API 同域部署，优先由 Nginx 转发 `/api/` 和 `/health`
|
||||
- 如果需要公网访问，建议至少加一层 Basic Auth、OIDC 或内网入口限制
|
||||
Reference in New Issue
Block a user