quantum-atlas 0.2.3__tar.gz

quantum_atlas-0.2.3/.env.example

@@ -0,0 +1,225 @@
+# QuantumAtlas 环境变量覆盖模板
+#
+# 复制本文件为 .env，然后只取消注释你明确想覆盖的变量。
+# 保持注释时，Go server 的 internal/config/config.go 会使用代码内置的
+# 本地开发默认值（旧 Python server 的 atlas/server/config.py 仍可参考，
+# 但已不是生产路径）。
+#
+# 不要提交真实 .env。token、API key、公网 URL 都应视为部署环境专属配置或密钥。
+#
+# ─── 命名规范 ─────────────────────────────────────────────────────────────
+# 项目自有变量统一加 `QATLAS_` 前缀，避免与系统 / 其他工具变量冲突。
+# 旧名（无前缀）仍作为 alias 保留，新代码请用 QATLAS_*。
+#
+# 第三方 / SDK 标准名不加前缀（业界生态已认这些名字，强行包就破坏复用）：
+#   - NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD       — Neo4j 官方驱动认这些
+#   - OPENAI_API_KEY / ANTHROPIC_API_KEY            — LLM SDK 默认读
+#   - MINERU_*                                       — MinerU 厂家 token 可跨工具共用
+# ──────────────────────────────────────────────────────────────────────────
+#
+# ─── 字段分类（client / server） ───────────────────────────────────────────
+# 同一份 .env 既给本机 client（qatlas 子命令）用，也给 server 用。按角色取舍：
+#
+#   ▸ 纯 client（不跑 server，所有调用走 QATLAS_SERVER_URL 指向远端）：
+#       必填：QATLAS_SERVER_URL
+#       可选：QATLAS_INSECURE         — 远端使用自签证书时设 1 跳过 TLS 校验
+#             QATLAS_WIKI_DIR         — `qatlas wiki list/show/search/lint` 都在本地
+#                                       git clone 的 wiki repo 上跑，跟 server 无关
+#             MINERU_API_TOKEN        — 只在本地跑 `qatlas mineru` 自费走自己配额时填
+#             QATLAS_TOKEN            — 写操作 (upload-pdf / upload-markdown /
+#                                       mineru-claim / 创建 share) 需要的 bearer
+#                                       token，从 https://<server>/token 拷过来；
+#                                       也可以用 `--token` 命令行覆盖
+#       不要写：QATLAS_SERVER_HOST/PORT、QATLAS_RAW_DIR、QATLAS_DATA_DIR、
+#               NEO4J_*、QATLAS_SHARE_*、QATLAS_USER_HEADER。
+#               client 上传 PDF 走 `--pdf <任意路径>`，不读 RAW_DIR；
+#               client 不监听端口，不连 Neo4j。
+#
+#   ▸ server（本机自己跑 `qatlas server`）：上面所有字段按需配置。
+# ──────────────────────────────────────────────────────────────────────────
+
+
+# ============================================================================
+# Client 侧（也允许 server 使用）
+# ============================================================================
+
+# API、share 链接和外部解析器使用的对外根地址。
+# 纯 client 必填，指向远端服务（如 https://quantum-atlas.ai）；
+# server 自跑时也用来生成 share URL。
+# alias: PUBLIC_BASE_URL
+# QATLAS_SERVER_URL=https://atlas.example.com
+
+# 跳过 TLS 证书校验。等价于客户端 CLI 加 `--insecure`。
+# 仅在 QATLAS_SERVER_URL 是自签 HTTPS（如开发环境 Caddy `tls internal`）时启用。
+# QATLAS_INSECURE=0
+
+# 客户端写操作 (`qatlas upload pdf`、`qatlas upload markdown`、
+# `qatlas mineru`、`POST /api/shares/`) 携带的 bearer token。
+# 服务端 authGuard 接受两种凭据：
+#   (a) PocketBase 用户 session token —— 浏览器登录后从
+#       https://<server>/token 拷过来（默认 14 天有效，隐式拥有所有权限）；
+#   (b) Personal Access Token (PAT) —— 浏览器登录后到
+#       https://<server>/pat 创建。**强制设置过期**（最长 365 天，
+#       无"永不过期"选项）+ **显式 scope opt-in**（默认空集 = 全 403），
+#       一次性显示明文，前缀 "qat_"，可随时在同一页面撤销。
+#       Scope 词表见 docs/contribution-workflow.md §2。
+# CI / nightly / 长跑脚本推荐用 (b)，避免每两周重新拷一次。
+# 命令行同名参数 `--token` 优先级高于本环境变量。
+# QATLAS_TOKEN=
+
+# 本地 wiki repo 路径，client 和 server 都用。
+#
+# 默认值：`<.env 所在目录>/../QuantumAtlas-Wiki`
+# （即兄弟 Git checkout，方便多人 PR / review；符合 Gollum / mkdocs 等成熟
+# wiki 项目的约定）。**不再**默认指向仓库内 `wiki/`——那样会让仓库
+# 累积大量 wiki commit，跟代码主线混在一起。
+#
+# 显式覆盖示例：
+#   QATLAS_WIKI_DIR=/srv/quantum/QuantumAtlas-Wiki  # 绝对路径
+#   QATLAS_WIKI_DIR=../QuantumAtlas-Wiki            # 相对 .env 所在目录
+#
+# alias: WIKI_DIR
+# QATLAS_WIKI_DIR=../QuantumAtlas-Wiki
+
+
+# ============================================================================
+# PocketBase / OAuth (server 内嵌 PocketBase, Go 二进制启动时自动注入)
+# ============================================================================
+
+# GitHub OAuth App credentials. 服务端 internal/auth/oauth.go 在 OnBootstrap
+# 时把它们同步到 users collection 的 OAuth2 providers。在
+# https://github.com/settings/developers (或 organization/settings/applications)
+# 创建 OAuth App，callback 填 https://<your-server>/api/oauth2-redirect。
+# GITHUB_CLIENT_ID=
+# GITHUB_CLIENT_SECRET=
+
+# GitHub 用户名白名单（逗号分隔）。**当前 handler 未实现**，
+# 设置此字段不会影响行为；保留 env 名是为了未来自动 admin 提权时不破坏 .env。
+# QATLAS_ADMIN_GITHUB_LOGINS=alice,bob
+
+# 强制 server 用 tcp4-only listener（默认 off）。**只在 host 被 v4-only
+# portproxy 包裹时打开**（典型场景：WSL2 + Windows netsh portproxy）。
+# 普通 Linux 云 VPS 不要打开 —— 默认 PocketBase 用 dual-stack v6 socket
+# 同时服务 v4 + v6 client；打开此项会关掉 v6 入口。
+# 取值：1 / true / yes / on / y / t = 启用。
+# QATLAS_FORCE_TCP4=0
+
+
+# ============================================================================
+# Server 侧
+# ============================================================================
+
+# 服务监听地址。位于本机反向代理后时使用 127.0.0.1；只有在明确配置好防火墙和
+# 反向代理边界时，才考虑监听 0.0.0.0。纯 client 不需要设置。
+# alias: SERVER_HOST / SERVER_PORT / SERVER_DEBUG
+# QATLAS_SERVER_HOST=127.0.0.1
+# QATLAS_SERVER_PORT=4200
+# QATLAS_SERVER_DEBUG=false
+
+# 存储根目录。**仅 server 使用**；纯 client 不需要（上传走 --pdf 任意路径）。
+#
+# 默认值（都遵循 XDG Base Directory 规范）：
+#   QATLAS_RAW_DIR     -> ${XDG_DATA_HOME:-$HOME/.local/share}/quantum-atlas/raw
+#   QATLAS_DATA_DIR    -> ${XDG_DATA_HOME:-$HOME/.local/share}/quantum-atlas/data
+#   QATLAS_PB_DATA_DIR -> ${XDG_DATA_HOME:-$HOME/.local/share}/quantum-atlas/pb_data
+#
+# 为什么不再默认在仓库内：
+#   - 仓库内的 raw/data/pb_data 让 git 状态混乱（必须维护 .gitignore 规则）
+#   - 仓库内的 raw/ 可能是 FUSE 挂载（rclone SMB），让 `go ./...` 卡死
+#   - 跟 12-factor / XDG / FHS 都背道
+#
+# 想覆盖到其他位置（FHS / 自建挂载点 / 共享盘）时显式赋值。
+#
+# alias: RAW_DIR / DATA_DIR / PB_DATA_DIR
+# QATLAS_RAW_DIR=
+# QATLAS_DATA_DIR=
+# QATLAS_PB_DATA_DIR=
+#
+# 注：pb_data 路径**只通过 QATLAS_PB_DATA_DIR 控制**——server 启动时
+# 自动转成 PocketBase 的 `--dir=` 传给底层。systemd unit 的 ExecStart
+# 不需要也不应该再硬写 `--dir=...`（cmdline 会覆盖 env，给排障添麻烦）。
+
+# 可选的常驻 share token，用于 canonical paper assets。
+# 只有在明确需要稳定、不过期的 /share/<token>/... URL 时才设置。
+# alias: SHARE_ACCESS_TOKEN
+# QATLAS_SHARE_ACCESS_TOKEN=<generate-a-long-random-token>
+
+# 通过 POST /api/shares 创建的动态 share token，如果请求未提供 expires_in，
+# 会使用这里的 TTL。取消注释即可覆盖代码默认值。
+# alias: DEFAULT_SHARE_EXPIRES_IN
+# QATLAS_DEFAULT_SHARE_EXPIRES_IN=600
+
+# 可选的服务端审计用户头，由反向代理、SSO 或 API gateway 注入。
+# 留空时不记录用户头；客户端不应手动设置这个头。
+# alias: USER_HEADER
+# QATLAS_USER_HEADER=X-Token-Subject
+
+
+# ============================================================================
+# 第三方 / SDK 标准名（无 QATLAS_ 前缀）
+# ============================================================================
+
+# Neo4j 连接配置。仅 server 需要。
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=
+
+# 可选的本地或服务端 LLM 提取密钥。
+# 如果提取流程在 QuantumAtlas 外部处理，或 ingest 使用 --no-extract，请保持未设置。
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# 可选的 MinerU 精准解析 API。client 跑 `qatlas mineru` 时也读取这些字段
+# （服务端不再帮 client 转 MinerU；token 配额属于触发命令的人）。
+# MINERU_API_TOKEN=
+# MINERU_API_BASE_URL=https://mineru.net
+# MINERU_MODEL_VERSION=vlm
+# MINERU_LANGUAGE=ch
+# MINERU_IS_OCR=false
+# MINERU_ENABLE_FORMULA=true
+# MINERU_ENABLE_TABLE=true
+# MINERU_POLL_INTERVAL=3
+# MINERU_TIMEOUT=1800
+
+# ============================================================================
+# 对象存储（RustFS / S3 兼容）— 仅 server 需要
+# ============================================================================
+# Go server 通过 internal/objstore 抽象层接 S3 兼容后端（minio-go SDK）。
+# 四个字段必须**同时**填或同时不填：
+#   - 全部留空 → 走本地 RawDir（LocalStore），仍然可用，适合 dev 起步；
+#   - 全部填上 → 走 S3 后端（S3Store），所有 PDF / markdown / JSON / 图片
+#                经过这个 bucket，server 端不再读写本地 RAW_DIR；
+#   - 半填 / 缺一不可 → 启动直接报错退出（避免 reader / writer 跑两套后端
+#                       的悄悄数据腐败）。
+#
+# 凭据生成：bash scripts/rustfs_bootstrap.sh （需要 RustFS root 凭据）
+# 详细部署 / rotate / Caddy 入口模板见 docs/storage-design.md
+# `## RustFS 部署后置：bucket / user / policy 自助配置`
+#
+# Endpoint 必须含 scheme（https:// 或 http://），minio-go 据此决定是否
+# 走 TLS。Bucket 名是单独参数，不要把 bucket 拼进 endpoint。
+#
+# QATLAS_S3_ENDPOINT=https://raw.your-domain.tld
+# QATLAS_S3_BUCKET=qatlas-raw
+# QATLAS_S3_ACCESS_KEY_ID=<bootstrap 脚本输出>
+# QATLAS_S3_SECRET_ACCESS_KEY=<bootstrap 脚本输出>
+#
+# QATLAS_S3_PUBLIC_ENDPOINT（可选） —— 仅用于给最终用户 client 签 presigned
+# URL 的"公网入口"。server↔RustFS 走 ENDPOINT（mesh / 内网，省一跳反代），
+# 但 share URL 里的 host 必须是公网可达的，否则浏览器拿到 307 直接连不通。
+# 留空（或与 ENDPOINT 相同）= 单 endpoint 模式，presign 用 ENDPOINT 签
+# —— 仅适合开发或全内网部署，不要在生产边缘节点这么干。
+#
+# 每个边缘节点用自己的公网入口，不共享：
+#   RackNerd .env: QATLAS_S3_PUBLIC_ENDPOINT=https://raw.quantum-atlas.ai
+#   Alibaba  .env: QATLAS_S3_PUBLIC_ENDPOINT=https://47.102.36.175:9000
+#
+# 部署要点：公网 host 必须反代到内网 RustFS 端口，且要 preserve Host header
+# —— SigV4 验签把 Host 算进 canonical request，Caddy 若改写 Host 会让
+# RustFS 报 SignatureDoesNotMatch。最小 Caddy 模板：
+#   raw.quantum-atlas.ai {
+#       reverse_proxy 10.144.18.10:9000 { header_up Host {host} }
+#   }
+#
+# QATLAS_S3_PUBLIC_ENDPOINT=https://raw.your-domain.tld
+

quantum_atlas-0.2.3/.github/workflows/go.yml

@@ -0,0 +1,77 @@
+name: Go (build + vet + test)
+
+on:
+  push:
+    branches: [main, feat/go-server]
+    paths:
+      - 'cmd/**'
+      - 'internal/**'
+      - 'go.mod'
+      - 'go.sum'
+      - 'pyproject.toml'
+      - 'pixi.lock'
+      - '.github/workflows/go.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'cmd/**'
+      - 'internal/**'
+      - 'go.mod'
+      - 'go.sum'
+      - 'pyproject.toml'
+      - 'pixi.lock'
+      - '.github/workflows/go.yml'
+  workflow_dispatch:
+
+jobs:
+  go:
+    name: Go (pixi-managed toolchain)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      # Pixi keeps the Go toolchain (+ gxx for cc shims) pinned in
+      # pyproject.toml [tool.pixi.dependencies], matching what local
+      # devs use. Reproducible across CI / dev machines.
+      - name: Install pixi
+        uses: prefix-dev/setup-pixi@v0.8.10
+        with:
+          pixi-version: v0.68.0
+          cache: true
+
+      # Cache the Go module + build cache. GOCACHE/GOMODCACHE are pointed
+      # at .gocache/ via pixi's [tool.pixi.activation.env] so both live
+      # inside the repo and are cacheable by a single path entry.
+      # Key on go.sum so cache invalidates when deps change.
+      - name: Cache Go modules + build artifacts
+        uses: actions/cache@v4
+        with:
+          path: .gocache
+          key: gocache-${{ runner.os }}-${{ hashFiles('go.sum') }}
+          restore-keys: |
+            gocache-${{ runner.os }}-
+
+      # 'pixi run vet' is scoped to ./internal/... ./cmd/... so it
+      # finishes fast even on cold cache. 'pixi run test-go' runs the
+      # unit suite (no network, no e2e). 'pixi run build' confirms the
+      # binary still links — caught in the past when go.mod's minimum
+      # Go version drifted above what conda-forge had available.
+      - name: pixi run vet
+        run: pixi run vet
+
+      - name: pixi run test-go
+        run: pixi run test-go
+
+      - name: pixi run build
+        run: pixi run build
+
+      - name: Upload server binary
+        uses: actions/upload-artifact@v4
+        with:
+          name: qatlas-server-binary-${{ github.sha }}
+          path: build/qatlas-server
+          retention-days: 7
+          if-no-files-found: error

quantum_atlas-0.2.3/.github/workflows/nightly.yml

@@ -0,0 +1,65 @@
+name: Nightly production smoke
+
+# Hits the live QuantumAtlas Go server (cmd/qatlas-server) through both edges
+# every night:
+#   - https://quantum-atlas.ai            (RackNerd, real LE cert)
+#   - https://47.102.36.175 | insecure    (Alibaba, tls internal self-signed)
+#
+# Both targets reverse-proxy back to 1810 over EasyTier mesh
+# (10.144.18.10:4200). Failures here usually mean either the user-mode
+# qatlas.service on 1810 fell over, or a Caddy reload broke the public
+# vhost.
+
+on:
+  schedule:
+    - cron: '0 18 * * *'   # UTC 18:00 = 北京时间次日 02:00
+  workflow_dispatch:        # 也允许手动从 Actions 页面触发
+
+jobs:
+  smoke:
+    name: Hit live production targets (Go server)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run production smoke against both edges
+        env:
+          # Default to both edges so the nightly is meaningful out of the
+          # box. Each target may carry `token-env=NAME` so the test
+          # picks up a per-host PAT — required when the edges run
+          # independent qatlas instances (active-active), since each
+          # has its own users DB and PATs don't cross-validate.
+          QATLAS_SERVER_TARGETS: ${{ secrets.QATLAS_SERVER_TARGETS || 'https://quantum-atlas.ai|token-env=QATLAS_TOKEN_RACKNERD,https://47.102.36.175|insecure|token-env=QATLAS_TOKEN_ALIBABA' }}
+          # Per-edge PATs. Mint each one on its own edge:
+          #   ssh <edge> sudo -u <user> /path/qatlas-server pat mint \
+          #     --user <email> --name nightly-ci \
+          #     --scopes shares:write --expires-in-days 365
+          # The active-active topology means RackNerd and Alibaba have
+          # independent SQLite user DBs — a PAT minted on one will get
+          # 401 on the other. Two secrets, one per edge.
+          QATLAS_TOKEN_RACKNERD: ${{ secrets.QATLAS_TOKEN_RACKNERD }}
+          QATLAS_TOKEN_ALIBABA: ${{ secrets.QATLAS_TOKEN_ALIBABA }}
+          # Legacy single-edge fallback (still honoured by
+          # Target.auth_token() when no per-target token resolves).
+          # Set this OR the per-edge tokens above; not both.
+          QATLAS_TOKEN: ${{ secrets.QATLAS_CI_TOKEN }}
+          # 'legacy' marker covers the old FastAPI-only ingest/* tests that
+          # the Go server intentionally does not implement; they must NOT
+          # be selected by this nightly run.
+        run: uv run pytest -rs -m "e2e and not legacy"
+

quantum_atlas-0.2.3/.github/workflows/pytest.yml

@@ -0,0 +1,50 @@
+name: Pytest
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'atlas/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/pytest.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'atlas/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/pytest.yml'
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run pytest (offline)
+        run: uv run pytest -rs -m "not network and not e2e"