# 配置说明

本文档描述 `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` 与归档目录 |