dd58c18fe3
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.
201 lines
4.9 KiB
Markdown
201 lines
4.9 KiB
Markdown
# 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 或内网入口限制
|