环境变量与配置边界¶
当前内容契约更新：固定来源 PDF 已恢复为 paper_access 开关下的鉴权字节， 关闭404，qa_、别名、Range、历史原件不能绕过。新内容在独立 qatlas-content 桶的 content/ 命名空间不可变发布：source 绑定确切 PDF SHA，arXiv vN 是语义版本、 S3VersionId 是物理版本、parse revision 是独立不可变身份；三者不可混用。 同 paper/SHA 可复用 source；冻结导入别名不同字节409（overwrite也不替换）。 解析上传必须完整支持的 Middle+Markdown，保留所有成员原名/字节，MD-only拒收； manifest最后核验发布且PG必需，重传新revision，不覆盖历史。旧MD/JSON/images忽略， 只在内容/PDF访问按需冻结旧PDF，不bulk回填、不删除旧桶；没有nightly/boot/入库自动推理。 下文涉及旧三桶覆盖、仅full.md+images、原PDF410/外部直链的段落保留为历史背景， 不作为当前操作规则。当前API/上传/续读统一见论文内容契约 与Upload API；完整read视图不是原Middle JSON。
主服务 qatlasd 的业务配置是 YAML-only，不是旧 Python 包的 .env 模式。默认文件为 ~/.qatlas/config.yaml，通过 qatlasd config init 创建、--config 选择；完整字段见服务端配置。旧 QATLAS_* 业务变量、MINERU_*、POSTGRES_* 等残留会触发明确错误，不会默默覆盖 YAML。
本页只保留目前仍有用途的环境变量类别，以及从旧配置迁移的入口。环境变量属于哪个进程，必须先分清。
进程/工具矩阵¶
使用方 |
配置入口 |
说明 |
|---|---|---|
主服务 |
|
OAuth、PG、S3、搜索和下载器均在 YAML；仅保留 PocketBase 启动参数等明确例外 |
独立 |
由 |
不安装于主仓，详见其独立仓库/CLI 文档 |
|
|
安装目标/超时，不是运行服务的设置 |
Docker Compose |
|
只选择镜像，服务内仍挂载 YAML |
|
|
独立程序的运行配置，不传进主服务 |
Vite dev server |
|
本地代理/HMR/调试；不是生产配置 |
Go 集成测试 |
build tag + 显式测试变量 |
不默认运行，不读取部署 |
文档刷新工具 |
|
作用于明确的文档输出/覆盖目录，不选择安装所需 UI |
安装器与 Compose¶
变量 |
使用方 |
用途 |
|---|---|---|
|
安装器 / Compose |
安装版本或镜像 tag；不设置运行中程序的版本 |
|
安装器 |
可写的安装目录，默认 |
|
安装器 |
GitHub owner/repo，默认官方仓库 |
|
安装器 |
每次下载/归档步骤时限，默认 60 秒，1..300 |
|
安装器 |
候选程序 |
|
Compose |
独立 app 镜像版本，仅由 Compose 插值 |
只在相应工具的一次调用中设置需要的变量，避免长期 export 后误传给主服务。不能用 QATLAS_VERSION 伪造 qatlasd --version，也不能用安装器 repo 覆盖主服务的 UI 下载来源；源码安装始终使用自身精确版本的官方 Release。
Go 开发和集成测试¶
Go 版本由根 go.mod 决定；GOCACHE、GOMODCACHE、GOPATH 可以按开发环境设置。不要关闭 GOSUMDB 或用修改 tag 绕过源码校验。正常发布使用 CGO_ENABLED=0，-race 则另需本机 C 编译器和 CGO_ENABLED=1，与已移除的 DuckDB 无关。
真资源 |
编译选择 |
仍需显式提供 |
|---|---|---|
PostgreSQL registry/corpus/usage/admin |
|
|
Fleet/worker/归档回调 PostgreSQL |
|
|
S3 测试桶 |
|
|
MinerU 真上传/转换 |
|
|
OpenAlex/出版商真请求 |
|
|
生产协议冒烟 |
|
|
普通测试中 internal/testutil.IntegrationEnabled 固定为 false；环境变量残留不能单独打开 internal/cmd 的真服务测试。加 tag 后仍需原有目标/开关。S3 真测试和生产冒烟还分别由自己的文件 build tag 隔离。
开发时仍应清除真实目标和凭据、使用临时 HOME，避免误读配置或传播 token。只检查集成路径是否可编译，可以使用 go test -tags=integration ./internal/... ./cmd/... -run '^$'；完整说明见贡献指南。不要把以上真实测试接入普通 PR 的必跑检查。
Vite 与下载节点¶
Vite 使用 VITE_DEV_API_TARGET、VITE_DEV_FAKE_AUTH、VITE_DEV_ALLOWED_HOSTS 及可选测试 PAT；语义和风险见 web/README.md。VITE_ 是客户端可暴露前缀，不能把真实凭据放入构建环境；fake-auth 不授予 API 权限。仅连接本地或明确获准的测试实例。
下载节点的完整环境契约见worker 配置。这些独立进程仍使用环境配置，不等于主服务恢复了 dotenv 模式。
Server：论文访问开关（self-hosted 可选）¶
当前使用 YAML 的 paper_access.enabled，默认 false。启用前确认版权、访问权限与外部服务预算；PDF/content/raw原件/图片随 paper_access 开关统一鉴权交付；已存PDF不需解析token，关闭404。见版权与资源访问。
Server-side MinerU¶
配置位于 paper_access.mineru：api_tokens 是 YAML 列表，模型、语言、OCR、并发与超时也在该段。不是进程 MINERU_* 环境变量，更不是客户端的用户配置。具体字段见服务端配置。
Client：qatlas 配置¶
客户端由 qatlas-cli 独立维护，通过 qatlas config path/show 查看实际配置。其 server_url 表示“我要连接谁”，与服务端 YAML 的 public_url（“我的公开入口”）不同；其认证与本地 MinerU 配置也不共享主服务配置文件。参见CLI 配置参考。
旧 quantum-atlas 0.21.0 仅是退役通知，不会安装新客户端，也不提供这些旧环境变量的兼容层。历史例子留在不可变 tag，不再作为 main 的可执行开发说明。