Skip to content

config-reference.md

Latest commit

 

History

History
175 lines (141 loc) · 12.2 KB

config-reference.md

File metadata and controls

175 lines (141 loc) · 12.2 KB
Raw

HeyBlog 配置参考

适合谁看

  • 想知道某个环境变量该配给哪个服务的开发者
  • 想确认默认值、Docker 覆盖值和本地运行差异的读者

建议前置阅读

不包含什么

最后核对源码入口

1. 统一配置入口

仓库内的应用级配置由 shared/config.py 中的 Settings.from_env() 统一加载。它会优先读取仓库根目录下的 .env，再回退到进程环境变量和代码默认值。

建议把本地可调配置维护在 .env，把团队基线维护在 .env.example。 Docker Compose 也会从仓库根目录的 .env 读取变量。

2. 应用级环境变量

变量 默认值 主要消费服务 说明
HEYBLOG_DB_PATH ./data/heyblog.sqlite persistence-api SQLite 模式下的数据库文件
HEYBLOG_DB_DSN 未设置 persistence-api 设置后切换到 PostgreSQL
HEYBLOG_SEED_PATH ./seed.csv crawler 种子文件路径
HEYBLOG_EXPORT_DIR ./data/exports crawler、persistence-api 导出图文件目录，也是 graph snapshot 的落盘目录
HEYBLOG_SEARCH_CACHE_DIR ./data/search-cache search 搜索缓存目录，默认会写 search-index.json
HEYBLOG_LOG_DIR ./logs 全部 Python 服务 统一日志根目录；服务会按类型写入 <log_dir>/app/、error/、access/
HEYBLOG_LOG_LEVEL INFO 全部 Python 服务 应用日志级别，例如 DEBUG、INFO、WARNING
HEYBLOG_LOG_FORMAT json 全部 Python 服务 日志格式；生产建议 json，也可设为其他值使用可读文本格式
HEYBLOG_LOG_FILE_ENABLED true 全部 Python 服务 是否写入分目录日志文件
HEYBLOG_LOG_CONSOLE_ENABLED true 全部 Python 服务 是否同时输出到控制台，方便 Docker logs 查看
HEYBLOG_LOG_RETENTION_DAYS 7 全部 Python 服务 自动清理超过该天数的小时切片日志
HEYBLOG_BACKEND_BASE_URL http://127.0.0.1:8000 frontend 浏览器代理层转发到公共 API 的目标地址
HEYBLOG_PUBLIC_BASE_URL http://127.0.0.1:3000 persistence-api 生成邮箱验证与密码重置链接时使用的公开前端基准地址
HEYBLOG_EMAIL_PROVIDER disabled persistence-api 用户生命周期邮件 provider。可选 disabled/noop 或 smtp；默认不连接邮件服务
HEYBLOG_EMAIL_FROM 空 persistence-api SMTP 邮件发件人地址；启用 smtp 时必须设置
HEYBLOG_EMAIL_DEV_EXPOSE_TOKENS false persistence-api 是否在验证/重置 API 响应中暴露 raw token/link。仅本地调试需要手动设置为 true
HEYBLOG_ADMIN_STATS_SCHEDULER_ENABLED true persistence-api 是否启动后台整点任务刷新 admin hourly stats；开启后不依赖打开 admin 页面
HEYBLOG_SMTP_HOST 空 persistence-api SMTP 服务器主机名
HEYBLOG_SMTP_PORT 587 persistence-api SMTP 服务器端口
HEYBLOG_SMTP_USERNAME 未设置 persistence-api SMTP 用户名；为空时不执行登录
HEYBLOG_SMTP_PASSWORD 未设置 persistence-api SMTP 密码；为空时不执行登录
HEYBLOG_SMTP_USE_TLS true persistence-api 是否在普通 SMTP 连接上使用 STARTTLS
HEYBLOG_SMTP_USE_SSL false persistence-api 是否使用隐式 SMTP-over-SSL 连接
HEYBLOG_SMTP_TIMEOUT_SECONDS 10.0 persistence-api SMTP 连接与发送超时时间
HEYBLOG_CRAWLER_BASE_URL http://127.0.0.1:8010 backend backend 调用 crawler 的内部地址
HEYBLOG_SEARCH_BASE_URL http://127.0.0.1:8020 backend backend 调用 search 的内部地址
HEYBLOG_PERSISTENCE_BASE_URL http://127.0.0.1:8030 backend、crawler、search 三个服务访问持久化边界的内部地址
HEYBLOG_USER_AGENT HeyBlogBot/0.1 (+https://example.invalid/heyblog) crawler 抓取请求使用的 User-Agent
HEYBLOG_REQUEST_TIMEOUT_SECONDS 10.0 backend、crawler、search 内部 HTTP client 默认超时
HEYBLOG_MAX_NODES_PER_RUN 10 crawler 单次 crawl 默认节点上限
HEYBLOG_MAX_PATH_PROBES_PER_BLOG 50 crawler 单站点路径探测上限
HEYBLOG_CANDIDATE_PAGE_FETCH_CONCURRENCY 4 crawler 友链候选页抓取并发度，最小为 1
HEYBLOG_RUNTIME_WORKER_COUNT 3 crawler runtime 持续抓取的 worker 数
HEYBLOG_RUNTIME_AUTO_START_INTERVAL_SECONDS 3600 crawler crawler 服务内置 idle 检测间隔；到点时若 runtime 不在工作则自动调用 runtime start
HEYBLOG_RAW_DISCOVERED_URL_LIMIT 1000000 crawler raw_discovered_urls 行数达到该值后拒绝启动 crawler，并让正在运行的 runtime 在下一次 claim 前自动停止；设为 -1 表示不限制
HEYBLOG_MAX_FETCHED_PAGE_BYTES 2000000 crawler 单个页面允许读取的最大字节数；超限后当前 crawl attempt 记为 FAILED 并记录错误分类，超大页不会继续进入解析阶段；这不会撤销已接受博客的 acceptance_status
HEYBLOG_FRIEND_LINK_DOMAIN_BLOCKLIST 空 crawler 逗号分隔的域名黑名单
HEYBLOG_FRIEND_LINK_TLD_BLOCKLIST 空 crawler 逗号分隔的顶级域黑名单
HEYBLOG_FRIEND_LINK_EXACT_URL_BLOCKLIST 空 crawler 逗号分隔的精确 URL 黑名单
HEYBLOG_FRIEND_LINK_PREFIX_BLOCKLIST 空 crawler 逗号分隔的 URL 前缀黑名单
HEYBLOG_DECISION_MODEL_ROOT ./runtime_resources/models/url_decision/current crawler、persistence-api 运行时 URL 决策模型根目录。建议将训练完成后、准备上线的模型发布到这个目录，而不是直接让服务读取 HeyBlog_model/data/model/
HEYBLOG_RSS_DISCOVERY_ENABLED true crawler 是否启用 RSS/Atom 订阅源发现成功决策层。开启后，候选博客主页若暴露可解析的订阅源会被直接判定为博客并记录 feed_url；缺失订阅源不算拒绝，会继续交给模型共识层。需要实时 fetcher，离线扫描会自动跳过
HEYBLOG_DECISION_MODEL_CONSENSUS_ENABLED true crawler、persistence-api 是否启用多模型负向共识决策层
HEYBLOG_DECISION_MODEL_CONSENSUS_STRATEGY weighted_average crawler、persistence-api 多模型共识策略。可选 weighted_average、majority_blog、any_blog；默认按模型评估指标加权平均概率
HEYBLOG_DECISION_MODEL_CONSENSUS_THRESHOLD 0.4 crawler、persistence-api weighted_average 策略下的全局保留阈值，加权平均 blog 概率低于该值时拒绝；当前值来自 blog-classification-redesign-20260523 validation split 调优

3. Docker Compose 里的默认覆盖

docker-compose.yml 为拆分运行时额外提供了这些默认值：

服务 Compose 中设置的变量 作用
frontend HEYBLOG_DOCKER_BACKEND_BASE_URL 浏览器代理到 backend
全部 Python 服务 HEYBLOG_DOCKER_LOG_DIR / HEYBLOG_LOG_LEVEL / HEYBLOG_LOG_FORMAT 容器内日志默认写到 /data/logs，并挂载到 volumes/logs
backend HEYBLOG_DOCKER_PERSISTENCE_BASE_URL 读取持久化边界
backend HEYBLOG_DOCKER_CRAWLER_BASE_URL 控制 crawler
backend HEYBLOG_DOCKER_SEARCH_BASE_URL 调用 search
crawler HEYBLOG_DOCKER_PERSISTENCE_BASE_URL 写入持久化边界
crawler HEYBLOG_DOCKER_SEED_PATH 使用挂载后的种子文件
crawler HEYBLOG_DOCKER_EXPORT_DIR 导出目录映射到 volumes/exports
crawler HEYBLOG_DOCKER_DECISION_MODEL_ROOT 容器内运行时模型根目录，默认指向挂载后的 /app/runtime_resources/models/url_decision/current
crawler HEYBLOG_DECISION_MODEL_CONSENSUS_STRATEGY / HEYBLOG_DECISION_MODEL_CONSENSUS_THRESHOLD 容器内模型共识策略与 weighted 阈值
search HEYBLOG_DOCKER_PERSISTENCE_BASE_URL 获取搜索快照
search HEYBLOG_DOCKER_SEARCH_CACHE_DIR 搜索缓存映射到 volumes/search-cache
persistence-api HEYBLOG_DB_DSN 启用 PostgreSQL 后端
persistence-api HEYBLOG_DOCKER_DECISION_MODEL_ROOT 全库规则重扫读取的容器内运行时模型根目录
persistence-api HEYBLOG_DECISION_MODEL_CONSENSUS_STRATEGY / HEYBLOG_DECISION_MODEL_CONSENSUS_THRESHOLD 全库规则重扫使用的模型共识策略与 weighted 阈值
persistence-api HEYBLOG_EMAIL_PROVIDER / HEYBLOG_EMAIL_FROM / HEYBLOG_SMTP_* 发送邮箱验证与密码重置邮件
persistence-api HEYBLOG_ADMIN_STATS_SCHEDULER_ENABLED 控制 admin hourly stats 后台整点刷新任务

3.1 运行时资源目录约定

3.1 日志目录约定

所有 Python 服务都通过 shared.observability 配置标准库 logging。日志先按类型分目录， 再按服务分目录，每个服务目录内保存该服务所有小时切片。默认本地写入：

logs/
  app/
    backend/
      backend-20260524-18.log
      backend-20260524-19.log
    crawler/
      crawler-20260524-18.log
  error/
    crawler/
      crawler-20260524-18.log
  access/
    backend/
      backend-20260524-18.log
    frontend/
      frontend-20260524-18.log

Docker Compose 默认把容器内 /data/logs 映射到 volumes/logs。app/ 记录正常应用事件，error/ 记录 warning/error/exception，access/ 记录 HTTP 请求事实。每个类型目录下按服务单独分目录；每个文件以小时为单位切片，超过 HEYBLOG_LOG_RETENTION_DAYS 的旧切片会在写日志时自动清理。跨服务 HTTP client 会转发 x-request-id，用于串联一次 frontend -> backend -> internal service 调用。

3.2 运行时资源目录约定

推荐把模型和类似资源拆成两层：

  • HeyBlog_model/data/：训练输出、实验报表、人工观察数据
  • runtime_resources/：已经被选中、准备给服务真正加载的运行时资源

当前推荐的 URL 决策模型发布目录是：

  • runtime_resources/models/url_decision/current/

这样本地 debug、pytest 和 Docker 只需要统一设置 HEYBLOG_DECISION_MODEL_ROOT，不需要直接依赖 HeyBlog_model/data/model/ 的实验输出结构。

4. Postgres 容器级变量

这些变量不是 shared/config.py 的一部分，但在 Docker 运行时影响 persistence-db 容器：

变量 默认值 说明
POSTGRES_DB heyblog 默认数据库名
POSTGRES_USER heyblog 默认数据库用户名
POSTGRES_PASSWORD heyblog 默认数据库密码

5. 本地手动启动时最容易踩的坑

  1. .env 中建议保留宿主机地址，Docker Compose 内部地址单独放到 HEYBLOG_DOCKER_* 变量里。
  2. crawler 和 search 即使本地跑，也会通过 HTTP 调 persistence-api，不是直接 import 仓储。
  3. frontend 不是直接访问 crawler 或 persistence-api，它只认 HEYBLOG_BACKEND_BASE_URL。
  4. 只改 HEYBLOG_DB_PATH 不会启用 PostgreSQL；真正切换数据库后端要设置 HEYBLOG_DB_DSN。
  5. 如果 Docker 内启用了模型共识，而宿主机的 runtime_resources/ 没有挂进去，服务会退化成 model_consensus_skipped_no_models，看起来像“规则开了”，实际不会过滤任何 URL。
  6. 默认模型共识策略是 weighted_average，会读取每个模型 run 的 metrics.json 并优先用 F1 作为权重；旧的“任意模型投 blog 即保留”行为需要显式设置 HEYBLOG_DECISION_MODEL_CONSENSUS_STRATEGY=any_blog。

6. 相关文档