Go 服务端 `qatlasd`¶

qatlasd 是 QuantumAtlas 的服务端：一个 Go 单 binary，提供 REST API、对象与元数据存储、鉴权（PAT + GitHub OAuth），并内嵌 SPA 前端。这一节覆盖部署运维（从"裸 VPS"到"生产可用 + 监控 + 备份 + 升级"），以及它对外暴露的 REST API 与服务端 CLI。

快速路径¶

安装与 service 注册

install-qatlasd.sh + qatlasd service install 的全自动 / 半自动 / 全手动三种模式（systemd 流派）。
Docker 部署

docker compose up -d 一键起 qatlasd + PostgreSQL（对象存储留外部）；ghcr.io 多架构 image；适合评估、k8s 友好部署。
反向代理模板

Caddy + nginx 配置示例，包含 SigV4 Host header preserve 的关键细节。
GitHub OAuth 接入

OAuth App 创建、callback URL、PocketBase provider 注入、多边缘节点的多 app 策略。
RustFS / S3 对象存储

bootstrap script 流程、IAM policy、bucket versioning、dual endpoint（presign 公网 + 内网传输）。
健康检查与监控

/api/health 接监控告警；degraded 状态怎么处理；常见报警模板。
备份与升级

pb_data SQLite 备份、RustFS bucket versioning + prune、PostgreSQL dump、binary 滚动升级。

API 与 CLI 参考¶

REST API 总览

/api/papers/* / /api/search / /api/pat/* / /api/theorems/* / /api/health 全 endpoint（method / path / auth / payload / response / status）。
Upload API 详解

POST /api/papers/{id}/upload-pdf 完整流程：sha256 dedup、in-transit guard、If-None-Match 并发安全、覆盖语义。
API Explorer

swaggo 生成的交互式 OpenAPI 文档，可展开浏览全部参数 / 请求体 / 响应 schema。
qatlasd CLI

serve / service install / pat mint / storage prune / superuser upsert 等运维命令。

完整运维参考¶

运维 ops 参考

完整长文：systemd、Caddy 模板、env 完整说明、RustFS 集成、PostgreSQL、多边缘——目前主体内容仍在这里，新页面是它的拆分版。
存储布局迁移

从老的"仓库内 wiki/raw/data/pb_data"迁到 XDG 路径的指南。仅老用户需要看。

部署形态¶

形态	推荐流派	拓扑示意
个人 / 实验室（评估）	docker compose 全家桶	qatlasd + postgres 一台（rustfs 外部可选）
个人 / 实验室（长期）	systemd 单机 + LocalStore	qatlasd 一台，无对象存储
团队（数据规模 < 100k 论文）	systemd 三件套（分机）	qatlasd@A · rustfs@NAS · postgres@内存大设备
生产单边缘	systemd + 公有云 S3 / 自托管 RustFS	qatlasd@VPS · rustfs@专属 VPS / R2 · postgres@专属 VPS
多边缘 active-active	systemd × N + 共享存储	qatlasd × N edges → 共享 rustfs + postgres（mesh）
k8s / Nomad / Swarm	docker image	helm chart / nomad job — image 当 building block

后续每个具体配置页都会说哪些选项适合哪个形态。

建议阅读顺序¶

systemd 流派（生产单边 / 多边 / 长期部署）：

install — 装好 binary + service
reverse-proxy — 前面挂 TLS
github-oauth — 用户能登录
PostgreSQL — paper registry + OpenAlex corpus 所在（生产必填；DSN 见 server-config，可放另一台机）
rustfs — 对象存储（生产强烈建议；可放另一台机或公有云）
health-and-monitoring — 接监控
backup-and-upgrade — 备份策略

docker 流派（一键评估 / k8s 友好）：

docker — compose 起栈 / standalone / docker run
reverse-proxy — 公网 TLS（可选；compose 内也能挂 caddy sidecar）
github-oauth — OAuth app 注册（跟流派无关）
health-and-monitoring — docker logs / 监控接入
backup-and-upgrade — bind mount 备份 + docker compose pull

Go 服务端 qatlasd¶