llm-intelligence/docs/CONFIGURATION.md

配置说明

本文档描述 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、run_intraday_price_watch.sh	无	真实采集所需；只查看历史数据或仅跑前端时可不配
PORT	否	cmd/server/main.go	8080	API Server 监听端口
API_AUTH_TOKEN	条件必填	cmd/server/main.go、API smoke / 外部调用	空	对外访问 /api/* 时推荐使用的 Bearer token；外部请求未携带合法 token 或 Basic Auth 时返回 401
API_BASIC_AUTH_USER	条件必填	cmd/server/main.go	空	对外访问 /api/* 的 Basic Auth 用户名；与 API_BASIC_AUTH_PASS 配套使用
API_BASIC_AUTH_PASS	条件必填	cmd/server/main.go	空	对外访问 /api/* 的 Basic Auth 密码
API_RATE_LIMIT_PER_WINDOW	否	cmd/server/main.go	60	/api/* 按来源 IP 的窗口限流阈值；设为 0 表示关闭内建限流
API_RATE_LIMIT_WINDOW_SEC	否	cmd/server/main.go	60	/api/* 限流窗口长度（秒）
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、run_intraday_price_watch.sh、run_intraday_discovery_watch.sh	当天日期	指定日报或日内链路日期，格式 YYYY-MM-DD
REPORT_RUN_KIND	否	generate_daily_report.go	manual	运行语义，如 scheduled / manual / historical_rebuild
REPORT_TRIGGER_SOURCE	否	generate_daily_report.go、materialize_daily_signals.go	cli	触发来源，如 cron / pipeline / intraday / intraday_discovery / rebuild_script
REPORT_IS_OFFICIAL_DAILY	否	generate_daily_report.go	false	是否属于正式日报产出
REPORT_RUNTIME_AUDIT	否	generate_daily_report.go	空	来源级运行审计摘要，通常由流水线脚本注入
INTRADAY_DISCOVERY_SEARCH_PROVIDER	条件必填	discover_intraday_news_candidates.go、run_intraday_discovery_watch.sh	空	候选发现搜索 provider 类型；计划支持 fixture / command_json / http_json
INTRADAY_DISCOVERY_SEARCH_COMMAND	条件必填	discover_intraday_news_candidates.go	空	当 INTRADAY_DISCOVERY_SEARCH_PROVIDER=command_json 时执行的搜索命令，stdout 必须输出 JSON 数组
INTRADAY_DISCOVERY_SEARCH_URL	条件必填	discover_intraday_news_candidates.go	空	当 INTRADAY_DISCOVERY_SEARCH_PROVIDER=http_json 时调用的搜索接口 URL
INTRADAY_DISCOVERY_SEARCH_FIXTURE	否	discover_intraday_news_candidates.go	空	搜索 provider 样例文件，用于 dry-run / 本地测试
INTRADAY_DISCOVERY_LLM_PROVIDER	条件必填	discover_intraday_news_candidates.go、run_intraday_discovery_watch.sh	空	候选归纳 LLM provider 类型；计划支持 fixture / command_json / http_json
INTRADAY_DISCOVERY_LLM_COMMAND	条件必填	discover_intraday_news_candidates.go	空	当 INTRADAY_DISCOVERY_LLM_PROVIDER=command_json 时执行的 LLM 命令，stdout 必须输出 JSON 数组
INTRADAY_DISCOVERY_LLM_URL	条件必填	discover_intraday_news_candidates.go	空	当 INTRADAY_DISCOVERY_LLM_PROVIDER=http_json 时调用的 LLM 接口 URL
INTRADAY_DISCOVERY_LLM_FIXTURE	否	discover_intraday_news_candidates.go	空	LLM provider 样例文件，用于 dry-run / 本地测试
INTRADAY_DISCOVERY_TIMEOUT_SEC	否	discover_intraday_news_candidates.go、verify_intraday_news_candidates.go	20	discovery provider 与验证抓取的默认超时秒数
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

export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
export PORT="8080"
export API_AUTH_TOKEN="replace-with-long-random-token"
# 或者：export API_BASIC_AUTH_USER="review" && export API_BASIC_AUTH_PASS="replace-with-password"
./server

正式日报调度

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

手工真实复跑

export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
export OPENROUTER_API_KEY="***"
bash scripts/run_real_pipeline.sh

日内价格追踪

export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
export OPENROUTER_API_KEY="***"
bash scripts/run_intraday_price_watch.sh

说明：

• 该入口只刷新价格 importer 与 daily_signal_snapshot
• 不生成正式 HTML / Markdown 日报
• 推荐先按每 4 小时一次调度，再根据外部源稳定性决定是否收紧到每 2 小时

日内候选发现与验证

export DATABASE_URL="postgres://app_user:***@db:5432/llm_intelligence?sslmode=disable"
export INTRADAY_DISCOVERY_SEARCH_PROVIDER="command_json"
export INTRADAY_DISCOVERY_SEARCH_COMMAND="/usr/local/bin/intraday-search --date $REPORT_DATE"
export INTRADAY_DISCOVERY_LLM_PROVIDER="command_json"
export INTRADAY_DISCOVERY_LLM_COMMAND="/usr/local/bin/intraday-llm --date $REPORT_DATE"
bash scripts/run_intraday_discovery_watch.sh

说明：

• 该入口只刷新候选池、验证轨迹与 daily_signal_snapshot 中的已验证事实
• 它不会直接写 daily_report，不会覆盖 /api/v1/reports/latest 对应的正式日报
• 搜索 / LLM provider 缺失时应明确报前置条件错误，不能伪装成“今日无新闻”
• leak_or_rumor 默认留在候选层，不进入正式日报事实

日报运行语义

项目用以下字段区分正式日报、手工复跑和历史补跑：

字段	说明	典型值
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

DATABASE_URL="host=/var/run/postgresql dbname=llm_intelligence user=long sslmode=disable" \
PORT="8080" \
go run ./cmd/server

说明：

• /health 仅允许本机或私网来源访问
• /api/* 对外访问默认要求 Bearer token 或 Basic Auth
• 本机与私网来源可直接访问，便于同机前端、验收脚本和内网反代联调

仅生成指定日期日报

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

真实采集并写库

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 与归档目录