入门指南¶
按你的角色选一条路径开始。每条路径都是「装好工具 → 跑一个最小可工作的例子 → 知道下一步往哪走」。
客户端由 qatlas-cli 独立仓库维护和发版，安装包为 PyPI qatlas-cli。安装本仓不会提供 qatlas 命令；已装过旧包 quantum-atlas 的用户请先完成迁移。
我是研究者¶
我想用 QuantumAtlas 查论文 / 拉论文资产。不需要装 server。
1. 装 client：
# 推荐：uv 全局工具（升级方便）
uv tool install qatlas-cli
# 或 pipx
pipx install qatlas-cli
# 或 pip
pip install qatlas-cli
qatlas --help
2. 指向远端 server：
# 一次性配好（写入平台原生 user-config 路径下的 config.yaml）
qatlas config set server_url https://quantum-atlas.ai
qatlas config path # 看真实文件路径
qatlas config show # 看当前所有解析值（敏感字段自动遮罩）
3. 跑起来：
论文数据不匿名可读——先在浏览器里用 GitHub 登录 server，然后：
# OAuth device-code 登录（拿到 papers:read PAT 写进 hosts.yml）
qatlas auth login -s <your-server>
# 拉一篇论文的 MinerU markdown（server 缓存未命中会自动 silent fetch + 转换）
# PDF 交付已停用；图片用 get images 显式获取
qatlas paper get markdown 2501.00010v1 -o paper.md
qatlas paper get images quant-ph/9508027 -o shor-images.zip
多 provider 搜索（本地 catalog + arXiv + OpenAlex，可选 Qdrant 语义检索）
走 SPA 的搜索页，或直接 POST /api/search（papers:read scope）。
下一步：
我是贡献者¶
我想上传论文 / 跑 MinerU。需要装 client + 申请一个 PAT。
1. 装 client（同上）
2. 登录：
qatlas auth login -s <your-server>
# 1) CLI 跟 server 要一个 8 位 user_code + 深链
# 2) 自动开本机浏览器到 https://<your-server>/device?user_code=WDJB-MJHT
# 3) 用 GitHub 登录后看到 Approve 表单，默认全勾所有 scope，可改名字 /
# 过期天数 / 取消不想要的 scope → 点 Approve
# 4) CLI 轮询拿到 token 写进 ~/.config/qatlas/hosts.yml
# SSH 远端 / 没 DISPLAY 的机器加 --no-browser，只打印 URL，
# 自己复制到任意有浏览器的设备（手机、自己工位…）打开即可
# qatlas auth login --no-browser -s <your-server>
# 验证
qatlas auth status
已经手上有 PAT 明文了？
浏览器自助打开 https://<your-server>/pat 创建一个，复制以 qat_ 开头的明文，然后用 --with-token 从 stdin 写进 hosts.yml：
echo qat_xxxxxxxxxxx | qatlas auth login -s <host> --with-token
（从 stdin 读而不是 argv 是为了 secret 不进 shell history / ps / CI runner log——跟 gh auth login --with-token 同款设计。）
3. 上传第一篇论文：
# 上传 PDF + 元数据 JSON
qatlas contrib pdf 2501.00010v1 --pdf paper.pdf
# 用本地 MinerU 配额解析后推回云端（先把 token 写进 yaml）
echo <your-jwt-from-mineru.net> | qatlas config set mineru_api_token
qatlas contrib mineru 2501.00010v1 --push-pdf
下一步：
上传论文资产 — sha256 dedup、冲突处理、
--overwrite用 MinerU 解析 — 单篇 / 队列模式 / 并发协作
管理 PAT — 撤销、轮换、scope 升降
我是运维者¶
我想部署 / 维护 qatlasd。
1. 装 binary：
TAG=vX.Y.Z # 替换为采用新格式的已公开版本；不是让你重装旧v0.34.0
curl -fL --proto '=https' --proto-redir '=https' \
"https://raw.githubusercontent.com/IAI-USTC-Quantum/QuantumAtlas/$TAG/cmd/qatlasd/install-qatlasd.sh" \
-o install-qatlasd.sh
# 审阅脚本后，从同一个版本安装
sh install-qatlasd.sh --version "$TAG"
# 或仅需Go（无Node/Sphinx）：
# go install "github.com/IAI-USTC-Quantum/QuantumAtlas/cmd/qatlasd@$TAG"
预编译程序已内嵌完整 UI，首次运行无需联网补资源；go install 首次 serve 自动获取精确版本 Release 的 UI、校验并缓存，后续离线复用。升级自动切换版本缓存，失败不会回退 latest。旧服务的安装脚本不识别新格式，迁移时必须从同一新 tag 取脚本。详见安装说明。
2. 准备 YAML：
qatlasd config init # ~/.qatlas/config.yaml，不覆盖已有配置
# 按服务器需要编辑 postgres.dsn、GitHub OAuth、对象存储等字段
qatlasd config show
服务端拒绝旧的应用配置环境变量，完整字段见配置参考。不需要手动选择或配置 UI 资源。
3. 注册成 systemd 服务：
# 交互式（确认 mode + YAML 路径 + unit 预览）
qatlasd service install
# CI / 全自动
sudo qatlasd service install --mode system \
--config "$HOME/.qatlas/config.yaml" --force
4. 验证：
curl http://127.0.0.1:4200/api/health
# 应该看到 {"code":200,"message":"API is healthy.","data":{...}}
下一步：
我是开发者¶
我想本地起 stack、改代码、跑测试、提 PR。
1. clone + 装依赖：
git clone https://github.com/IAI-USTC-Quantum/QuantumAtlas.git
cd QuantumAtlas
# 源码编译与测试不需要前端产物
CGO_ENABLED=0 go build -o build/qatlasd ./cmd/qatlasd
# 要运行本地dev UI：先按贡献指南完成Sphinx两站+npm完整构建，再
CGO_ENABLED=0 go build -tags embedui -o build/qatlasd ./cmd/qatlasd
主仓的单元、部署结构和冒烟 fixture 测试使用 Go，不再需要 pytest。根 Python/Pixi 环境已移除；Sphinx/MkDocs 和 CI 辅助脚本仅使用独立文档依赖或标准库。这不会安装 qatlas；需要 CLI 联调时，按上面的独立客户端安装步骤操作。CLI 自身的代码修改与测试请到 qatlas-cli 仓库。
2. 起本地 Web 服务：
# 完整UI构建命令见「贡献指南 → 完整 UI 构建」，只提交源码
./build/qatlasd config init
# 编辑 ~/.qatlas/config.yaml；例如postgres.dsn（只指向测试数据库）
./build/qatlasd serve --http=127.0.0.1:4200
访问：
入口 |
URL |
|---|---|
SPA |
|
PocketBase admin UI |
|
PAT 管理 |
|
API 健康 |
4. 跑测试：
# 部署结构与本地 HTTP fixture：离线，不启动容器/业务服务
go test ./tests/...
# 在贡献指南的临时HOME/净环境隔离块内执行
CGO_ENABLED=0 go test ./internal/... ./cmd/... ./web ./tests/...
# 真资源测试另需 -tags integration + 明确的测试目标；生产 e2e 不默认启用
# 前端 build + type check
(cd web && npm run build)
下一步：
从旧包 quantum-atlas 迁移¶
quantum-atlas 0.21.0 是仅含元数据的最终迁移版：没有 qatlas Python 模块、parser 库或 console entry，没有运行时依赖，也不会自动安装 qatlas-cli。升级旧包不等于安装新 CLI；旧包残留的 Python helpers 已退役，并非主仓继续提供的库 API。
选择最初安装旧包的工具，只执行对应的一组命令。pip 用户需先激活原来的虚拟环境（如有），不要跨安装器混用：
uv tool¶
uv tool uninstall quantum-atlas
uv tool install qatlas-cli
pipx¶
pipx uninstall quantum-atlas
pipx install qatlas-cli
pip¶
pip uninstall quantum-atlas
pip install qatlas-cli
两包已共存时，卸载之后重装新包
旧发行版可能与 qatlas-cli 共享模块或命令路径；卸载 quantum-atlas 时可能把它们一起移除。即使新包显示「已安装」，也必须在旧包卸载之后用对应安装器重装：
# 三选一，与原安装器一致
uv tool install --reinstall qatlas-cli
# 或
pipx reinstall qatlas-cli
# 或
pip install --force-reinstall qatlas-cli
不要删除 ~/.config/qatlas（macOS / Windows 保留对应平台的配置目录），其中的配置和凭据无需因包名迁移而清除。最后运行 qatlas --help、qatlas config path 验证安装和配置路径。客户端后续升级与问题反馈请到 qatlas-cli 仓库。
通用配置：client YAML / server .env¶
v0.17.0 起 client 和 server 配置完全分离：
Client (
qatlas): YAML，由platformdirs选定位置（Linux~/.config/qatlas/、macOS~/Library/Application Support/qatlas/、Windows%APPDATA%\qatlas\）。首次跑任何qatlas <cmd>自动创建模板——不需要qatlas config init步骤。最小配置：
# config.yaml — auto-created on first qatlas invocation; edit directly or via `qatlas config set` server_url: https://quantum-atlas.ai # insecure: true # 仅当远端用自签证书 # token: qat_xxxxxxxx # 需要写操作时 # mineru_api_token: jwt_... # 仅当本地跑 qatlas contrib mineru
或用
qatlas config set维护：qatlas config set server_url https://quantum-atlas.ai。Server (
qatlasd): 三入口 CLI flag > OS env >.env文件 > default。最小.env见 reference/env-vars 和模板.env.example。
获取帮助¶
看 Python 客户端（客户端工作流）
查 参考（字段 / 格式 / 环境变量）
翻 FAQ