qatlasd 服务端 CLI 参考¶
qatlasd 是本仓的 Go 服务端；独立 Python 客户端 qatlas 来自 qatlas-cli，两者命令与配置文件不同。预编译发行程序内嵌完整 UI，源码安装按版本自动补齐 UI，详见安装说明。
qatlasd [global flags] <subcommand> [args...]
当前主命令为 config、serve、service、pat、storage、papers、openalex、users、downloader、superuser。以安装版本的 --help 为准，不假定 PocketBase 的所有可选命令都已注册。
全局参数与配置¶
参数 |
用途 |
|---|---|
|
YAML 文件；默认 |
|
显式覆盖 PocketBase 数据目录；未给时由 YAML |
|
PocketBase 开发日志/SQL 输出；不要在生产启用 |
|
PocketBase 设置加密 key 所在的环境变量名，属于上游明确保留的接口 |
|
PocketBase SELECT 查询超时，默认 30 秒 |
|
打印服务版本；独立于配置、数据库与 UI 下载 |
|
命令帮助 |
业务配置不再提供逐字段的 env 或 CLI 覆盖。--postgres-dsn、--system-pat、--raw-dir、--dotenv-path 等旧参数已移除；请使用当前 YAML 配置。凭据不要放入命令行参数或 shell 历史。
config：初始化和检查 YAML¶
qatlasd config init
qatlasd config init --config /path/to/config.yaml
qatlasd config path --config /path/to/config.yaml
qatlasd config show --config /path/to/config.yaml
init 默认拒绝覆盖；只有明确要替换且已备份时才使用 --force。新文件为 0600。show 默认脱敏，非默认服务用户还需核对文件读权限。默认模板和仓库根 config.example.yaml 保持同步，但启动逻辑始终以 Go 配置结构与校验为准。
serve：启动 HTTP server¶
qatlasd --config /path/to/config.yaml serve
qatlasd --config /path/to/config.yaml serve --http=127.0.0.1:4200
应用默认
http_addr为127.0.0.1:4200；PocketBase 的通用帮助可能列出其自身默认值，真正的应用启动会注入 YAML 设置。--http、--https、--origins等继承选项见serve --help；显式--http/--dir胜过对应 YAML 值。无内嵌资源时，serve 在监听之前校验/准备精确版本 UI。其他命令不为 UI 联网；本地 dev 构建需要先完成完整 UI 构建并使用
-tags embedui。后端连接、迁移和后台任务只在服务启动路径按配置初始化。不要为了查看版本而启动生产服务。
OAuth、PG、S3 等真实配置写 YAML；Docker 挂载该文件，不使用旧
--env-file业务配置方式。
service：管理 systemd / launchd 服务¶
qatlasd service <install|uninstall|start|stop|restart|status>
service install¶
# 只看将要写入的配置（非TTY也需mode和force）
qatlasd service install --mode user --config /path/to/config.yaml --dry-run --force
# 审阅并授权后，去掉dry-run才会注册并启动服务
qatlasd service install --mode user --config /path/to/config.yaml --force
参数 |
默认/行为 |
|---|---|
|
|
|
TTY 询问；非 TTY 必填 |
|
已存在的默认 YAML 或显式路径；写进 unit 的程序参数 |
|
|
|
只显示，不写 unit、不 reload、不启动 |
|
跳过确认、允许覆盖 unit；不是绕过 YAML 校验 |
system mode 需要相应权限；从预定服务用户的 shell 运行 sudo /absolute/path/qatlasd ... --mode system，不要混用 sudo ... --mode user。具体身份/属主与迁移注意事项见安装与 service 注册。安装器本身不注册或重启服务。
systemd hardening¶
生成的 unit 包括 NoNewPrivileges、PrivateTmp、ProtectSystem=full 等，数据路径来自已解析的服务身份与配置路径。ReadWritePaths 中的目录要预先存在；自定义 YAML 存储路径或额外 sandbox 要自行核对。无内嵌 UI 的安装还需要运行用户的缓存目录可写，见安装文档。
管理已安装服务¶
qatlasd service status --mode user
qatlasd service restart --mode user
# system服务明确选system，不要误查user unit
sudo qatlasd service status --mode system
stop / uninstall 会影响正在运行的服务；卸载不会删除配置、数据库、对象存储或 UI 缓存。它们不是离线开发检查命令。
pat：本机 PAT 维护¶
直接访问此服务的数据目录，和浏览器 /api/pat 的操作边界不同。用 qatlasd pat --help 查看当前参数；示例：
qatlasd --config /path/to/config.yaml pat scopes
qatlasd --config /path/to/config.yaml pat list --json
# mint / revoke 会创建或删除凭据，只在明确授权后执行
mint 的明文仅输出一次，应安全保存；不要提交日志或将它用于不受控的 Vite 代理。scope 以当前输出为准，不再把已迁出的 theorem/wiki scope 当作主仓必备项。
storage、papers 与 openalex¶
storage：S3/RustFS 维护，包括版本清理。storage prune默认预览；真正删除需要明确--yes，见 RustFS。papers：PostgreSQL registry 维护、对象存储导入/迁移相关操作；具体命令见qatlasd papers --help。openalex：OpenAlex corpus 导入；连接数据库、下载快照或创建索引会产生实际资源消耗，不属于默认单元测试。
qatlasd --config /path/to/config.yaml storage prune --older-than 90d --keep-last 5
qatlasd --config /path/to/config.yaml papers --help
qatlasd --config /path/to/config.yaml openalex --help
downloader probe：明确的在线诊断¶
qatlasd downloader probe 会对论文执行真实的 OA/API/出版商策略链，可能调用浏览器、代理或 LLM。它不是本地 fixture，不因名字为 probe 就无需授权。需要 paper_access.enabled 等相关配置，参数见当前版本的 downloader probe --help，行为见下载器说明。
不要把在线 probe 加入普通 Go CI；其接入目标、凭据和可消耗额度须由操作者明确指定。
users、superuser 与数据库迁移¶
users 检查此实例的 PocketBase 用户；superuser 管理 PocketBase 管理员。创建/修改管理员需要运维授权，密码不要写成可复制的固定示例。
主仓的 PocketBase 迁移在各领域 Go 包中注册；PostgreSQL goose SQL 位于 internal/registry/migrations/。当前主命令没有通用的 qatlasd migrate down 回滚入口，也没有主仓 pb_migrations/ 源码目录。数据库降级必须按版本说明和一致性备份处理，换回旧 binary 不代表回滚了 schema。
查看准确帮助¶
qatlasd --version
qatlasd --help
# 子命令帮助可能需要可读YAML，但不会执行serve/管理动作
qatlasd --config /path/to/config.yaml serve --help
qatlasd --config /path/to/config.yaml service install --help