Docs Hub

主题

好学云谱云端数据中心 ​

目标模式：

text
好学 / 寸光集账号认证
        ↓
好学云谱 Docker 后端
        ↓
Web / 手机 APK / 电脑版

数据互通范围 ​

同一个账号登录后，以下数据会同步到 Docker 后端，并在 Web、手机端、电脑端之间互通：

  • 家族资料
  • 人物成员
  • 人生事件
  • 谱序、题词、纸质家谱、影像附件等谱牒资料
  • 设置项
  • 快照备份

本机 IndexedDB 仍会保留一份离线缓存。离线时可以继续查看最近一次同步的数据；联网后会继续推送编辑内容。

Docker 启动 ​

powershell
docker compose up -d --build

默认地址：

text
http://localhost:5173

JIAPU_AUTH_SECRET 留空即可——服务端首次启动会自动生成随机密钥并存入数据卷（yunpu-data:/app/data/.session-secret），每实例唯一、重启复用，新手无需配置。多实例或自建想固定密钥时再手动设置。建议通过 HTTPS 域名反向代理到容器。

云端数据保存在 Docker volume：

text
yunpu-data:/app/data

账号数据文件位于容器内：

text
/app/data/accounts

高级配置（可选环境变量） ​

发给最终用户的 docker-compose.example.yml 是零配置模板（只含端口、自动密钥、可选 OTA）。下面这些是自建/运维场景才用的高级项,默认鉴权走线上站点接口,无需填写。要启用就在 compose 的 environment 或 .env 里加:

变量说明默认
HXPT_SITE_URL / PTANG_SITE_URL鉴权站点地址(已内置,一般不改)https://www.hxpt.org / https://ptang.top
JIAPU_AUTH_DISABLED1 关闭鉴权(仅开发,生产保持 0)0
JIAPU_CORS_ORIGINS允许携带凭证的额外前端来源(逗号分隔;同源无需配)空
HXPT_DB_HOST / _PORT / _USERNAME / _PASSWORD / _DATABASE直连 HXPT MySQL 账号库(留空则只用线上接口)空
PTANG_DATABASE_URL / PTANG_ADMIN_PASSWORD直连 PTANG Postgres 账号库空
YUNPU_API_BASE前端 API 基址(反代/独立域名部署时填)空
YUNPU_UPDATE_MANIFEST_URLOTA 更新清单地址(留空则客户端「检查更新」提示未配置)空

注:JIAPU_AUTH_SECRET 留空时,服务端自动生成随机密钥并落盘 .session-secret(0600 权限,原子写入)。设置时必须 ≥32 字符且不能是占位词(如 change-this/secret...),否则拒绝启动。

Web 端 ​

Web 端直接访问 Docker 后端地址即可。因为前端和 API 同源，runtime-config.js 可以保持默认空地址。

手机端 / APK ​

手机端不需要为每个用户单独打包后端地址。登录界面会显示“云端地址”，用户填写自己部署的 Docker 后端即可，例如：

text
https://yunpu.example.com
http://192.168.1.10:5173

如果希望给 APK 预填一个默认地址，可以在打包前设置：

powershell
$env:YUNPU_CLOUD_URL="https://yunpu.example.com"
npm run package:apk

也兼容旧变量名：

powershell
$env:YUNPU_MOBILE_API_BASE="https://yunpu.example.com"
npm run package:apk

电脑版 ​

电脑版同样可以在登录界面填写“云端地址”。如果希望预填默认地址，可以通过环境变量指定：

powershell
$env:YUNPU_CLOUD_URL="https://yunpu.example.com"
npm run package:desktop-exe

也可以在运行目录放置 runtime-config.local.json：

json
{
  "apiBase": "https://yunpu.example.com"
}

同步接口 ​

登录认证：

text
POST /api/auth/login
GET  /api/auth/session
POST /api/auth/logout

云端数据：

text
GET    /api/sync/state
PUT    /api/sync/state
DELETE /api/sync/state

客户端登录后会保存 token，并在同步请求中使用：

http
Authorization: Bearer <token>

PUT /api/sync/state 带 baseRevision，用于检测多端并发编辑。如果云端 revision 已变化，后端返回 409，客户端会合并后重试。