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.
131 lines
5.7 KiB
Markdown
131 lines
5.7 KiB
Markdown
# 配置说明
|
|
|
|
本文档描述 `llm-intelligence` 在本地、CI 与生产环境中的关键配置项，以及各脚本的运行语义。
|
|
|
|
## 配置原则
|
|
|
|
- 生产环境优先使用容器平台、systemd 或 CI/CD 注入环境变量，不要依赖仓库内 `.env`
|
|
- `.env.example` 只作为示例，不应存放真实密钥
|
|
- 避免在 `.env.local` 与 `.env` 中重复定义同一变量
|
|
- 由于不同脚本的加载方式不同，重复定义时优先级并不完全一致
|
|
- Shell 脚本通常按 `.env.local` 然后 `.env` 顺序 `source`，后者可能覆盖前者
|
|
- `generate_daily_report.go` 会优先保留已存在环境变量，并优先保留较早注入的值
|
|
|
|
生产环境建议：所有关键变量统一在部署系统中注入，仓库内 `.env*` 仅用于开发。
|
|
|
|
## 关键环境变量
|
|
|
|
| 变量名 | 必填 | 使用方 | 默认值 | 说明 |
|
|
|--------|------|--------|--------|------|
|
|
| `DATABASE_URL` | 是 | API Server、迁移、采集、日报、备份恢复、验收脚本 | 无 | PostgreSQL 连接串，缺失时多数核心脚本会直接失败 |
|
|
| `OPENROUTER_API_KEY` | 条件必填 | `fetch_openrouter.go`、`run_real_pipeline.sh`、`run_daily.sh` | 无 | 真实采集所需；只查看历史数据或仅跑前端时可不配 |
|
|
| `PORT` | 否 | `cmd/server/main.go` | `8080` | API Server 监听端口 |
|
|
| `FEISHU_WEBHOOK` | 否 | `run_daily.sh`、`feishu_alert.sh` | 空 | 正式日报失败时发送飞书告警 |
|
|
| `REPORT_OUTPUT_DIR` | 否 | `generate_daily_report.go` | `reports/daily` | 日报主产物输出目录 |
|
|
| `REPORT_DATE` | 否 | `generate_daily_report.go`、`rebuild_historical_report.sh` | 当天日期 | 指定日报生成日期，格式 `YYYY-MM-DD` |
|
|
| `REPORT_RUN_KIND` | 否 | `generate_daily_report.go` | `manual` | 运行语义，如 `scheduled` / `manual` / `historical_rebuild` |
|
|
| `REPORT_TRIGGER_SOURCE` | 否 | `generate_daily_report.go` | `cli` | 触发来源，如 `cron` / `pipeline` / `rebuild_script` |
|
|
| `REPORT_IS_OFFICIAL_DAILY` | 否 | `generate_daily_report.go` | `false` | 是否属于正式日报产出 |
|
|
| `REPORT_RUNTIME_AUDIT` | 否 | `generate_daily_report.go` | 空 | 来源级运行审计摘要，通常由流水线脚本注入 |
|
|
| `PHASE6_PORT` | 否 | `verify_phase6.sh` | 自动挑选 `18080-18120` | Phase 6 验收时临时启动 API Server 的端口 |
|
|
| `LIGHTHOUSE_PORT` | 否 | `verify_lighthouse.sh` | `4173` | Lighthouse 预览端口 |
|
|
| `LIGHTHOUSE_SCORE_THRESHOLD` | 否 | `verify_lighthouse.sh` | `80` | 前端性能分数门槛 |
|
|
| `LIGHTHOUSE_FCP_THRESHOLD_MS` | 否 | `verify_lighthouse.sh` | `2000` | 首次内容绘制门槛 |
|
|
| `VERIFY_DB_NAME` | 否 | `verify_common.sh` | `llm_intelligence` | SQL 型验收脚本默认连接的数据库名 |
|
|
|
|
## 推荐的生产注入方式
|
|
|
|
### API Server
|
|
|
|
```bash
|
|
export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
|
|
export PORT="8080"
|
|
./server
|
|
```
|
|
|
|
### 正式日报调度
|
|
|
|
```bash
|
|
export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
|
|
export OPENROUTER_API_KEY="***"
|
|
export FEISHU_WEBHOOK="https://open.feishu.cn/..."
|
|
bash scripts/run_daily.sh
|
|
```
|
|
|
|
### 手工真实复跑
|
|
|
|
```bash
|
|
export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
|
|
export OPENROUTER_API_KEY="***"
|
|
bash scripts/run_real_pipeline.sh
|
|
```
|
|
|
|
## 日报运行语义
|
|
|
|
项目用以下字段区分正式日报、手工复跑和历史补跑：
|
|
|
|
| 字段 | 说明 | 典型值 |
|
|
|------|------|--------|
|
|
| `run_kind` | 运行类型 | `scheduled` / `manual` / `historical_rebuild` |
|
|
| `trigger_source` | 触发来源 | `cron` / `pipeline` / `rebuild_script` / `cli` |
|
|
| `is_official_daily` | 是否视为最新正式日报 | `true` / `false` |
|
|
| `summary_md` | 运行摘要与审计 | 包含 `REPORT_RUNTIME_AUDIT` 拼接结果 |
|
|
|
|
`/api/v1/reports/latest` 只返回：
|
|
|
|
- `status='generated'`
|
|
- `output_path` 非空
|
|
- `is_official_daily=true`
|
|
|
|
这意味着：
|
|
|
|
- 手工复跑不会覆盖“最新正式日报”
|
|
- 历史补跑不会冒充当天正式结果
|
|
- 如果正式日报写库成功但落盘产物丢失，元数据查询可成功，文件拉取接口会返回 `404`
|
|
|
|
## 产物路径约定
|
|
|
|
| 类型 | 路径 |
|
|
|------|------|
|
|
| 当天 Markdown | `reports/daily/daily_report_YYYY-MM-DD.md` |
|
|
| 当天 HTML | `reports/daily/html/daily_report_YYYY-MM-DD.html` |
|
|
| 归档 Markdown | `reports/daily/YYYY/MM/daily_report_YYYY-MM-DD.md` |
|
|
| 归档 HTML | `reports/daily/YYYY/MM/daily_report_YYYY-MM-DD.html` |
|
|
| 每日日志 | `/tmp/llm_hub_daily_YYYY-MM-DD.log` |
|
|
| 备份目录 | `/tmp/llm_hub_backups` |
|
|
|
|
## 最小可运行配置
|
|
|
|
### 仅启动 API Server
|
|
|
|
```bash
|
|
DATABASE_URL="host=/var/run/postgresql dbname=llm_intelligence user=long sslmode=disable" \
|
|
PORT="8080" \
|
|
go run ./cmd/server
|
|
```
|
|
|
|
### 仅生成指定日期日报
|
|
|
|
```bash
|
|
DATABASE_URL="host=/var/run/postgresql dbname=llm_intelligence user=long sslmode=disable" \
|
|
REPORT_DATE="2026-05-13" \
|
|
go run -tags llm_script ./scripts/generate_daily_report.go
|
|
```
|
|
|
|
### 真实采集并写库
|
|
|
|
```bash
|
|
DATABASE_URL="host=/var/run/postgresql dbname=llm_intelligence user=long sslmode=disable" \
|
|
OPENROUTER_API_KEY="***" \
|
|
go run ./scripts/fetch_openrouter.go -strict-real -db "$DATABASE_URL" -api-key "$OPENROUTER_API_KEY"
|
|
```
|
|
|
|
## 配置错误的典型症状
|
|
|
|
| 症状 | 可能原因 | 排查方向 |
|
|
|------|----------|----------|
|
|
| `/health` 返回 `503 database not configured` | `DATABASE_URL` 未注入到 API Server | 检查进程环境变量 |
|
|
| `run_real_pipeline.sh` 直接退出 | `OPENROUTER_API_KEY` 或 `DATABASE_URL` 缺失 | 检查 `.env` 或部署配置 |
|
|
| `/api/v1/reports/latest` 返回 `404` | 没有正式日报或 `is_official_daily=false` | 查 `daily_report` 表 |
|
|
| 最新日报元数据存在，但 `/html` 返回 `404` | `output_path` 对应文件丢失 | 检查 `reports/daily` 与归档目录 |
|