dsh-store-server

生产环境务必配置

1. 管理员口令：首次打开管理页自动进入「首次使用 · 设置管理员密码」流程（≥8 位，先到先得，部署后请尽快设置）；也可提前用 ADMIN_TOKEN 环境变量指定；
2. GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET / JWT_SECRET（GitHub 登录）；
3. OAUTH_CALLBACK_URL（反代/域名场景，需与 OAuth App 注册的回调地址完全一致）；
4. GITHUB_TOKENS（同步抓取 token 池）。

密钥不在部署时必填：搜索 token（可多枚）、OAuth、JWT、管理员密码、注册开关等均可在管理端「配置中心」修改（每项独立保存、保存即热更新；JWT 更换后全员重新登录）。

---

使用说明

1. 获取 GitHub 搜索 token（同步插件库必需）

插件库的自动收录依赖 GitHub Search API，需要一枚 classic PAT：

1. 打开 GitHub → 右上角头像 → Settings → 左侧 Developer settings → Personal access tokens → Tokens (classic)；
2. 点 Generate new token (classic)，Note 随意（如 dsh-store-sync），有效期自选；
   • 权限（Scopes）：只需公开库搜索，全部不勾选即可（Search API 认证请求即可获得 30 次/分钟额度；如提示权限不足可勾选 public_repo）；
3. 生成后立即复制（只显示一次），形如 ghp_xxxxxxxxxxxxxxxxxxxx；
4. 填入本服务端（二选一）：
   • 管理端 → 配置中心 → 搜索 token（一行一枚，可填多枚自动轮换，保存即热更新），或
   • 环境变量 GITHUB_TOKENS（逗号分隔多枚）；
5. 保存后同步自动启用：SYNC_TOPIC 默认为 dsh-plugin（只收录打了该 topic 的仓库），管理端可随时「▶ 立即抓取」。

未配置搜索 token 时：同步与登录功能休眠，其余（浏览/下载计数/管理端）不受影响。

2. 登录配置（用户 GitHub 登录）

1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App：
   • Homepage URL：你的服务器地址；
   • Authorization callback URL：必须与管理端配置的 OAUTH_CALLBACK_URL 完全一致（默认按请求 host 拼接，反代/域名场景需显式设置）；
2. 拿到 Client ID / Client Secret，连同自拟的 JWT_SECRET（签名密钥，≥16 位随机串）填入管理端配置中心（或环境变量）；
3. 保存即生效（JWT 更换后全员重新登录）。

配置完成后，用户在客户端「我的」页点「立即登录 GitHub」→ 新窗口完成授权 → token 自动回传并存到本地，全程无需复制粘贴。

3. 管理端登录（管理员）

• 首次使用：打开 http://:8080/admin → 进入「首次使用 · 设置管理员密码」流程（≥8 位，先到先得）→ 之后用该密码登录；
• 也可部署时用环境变量 ADMIN_TOKEN 预置口令；生产环境两者皆未配置时管理端整体 503（防后门）；
• 登录后 token（X-Admin-Token）自动保存在浏览器本地（dshs_admin_token），下次打开免输入；
• 管理端登录口令与用户登录（OAuth）完全独立，互不影响。

4. 客户端登录 token 在哪

• 用户登录 token 由 OAuth 授权后自动回传，保存在客户端浏览器本地存储（dsh_store_token），不需要手动获取或粘贴；
• 换电脑/换环境：重新打开商城「我的」→ 登录一次即可，云端组合/订阅/安装记录自动拉回；
• 未登录也能浏览、搜索、安装插件（数据通道开放）；登录仅用于云端同步与社区功能（发布插件/组合、订阅、点赞）；
• 纯离线演示模式（未配置 OAuth 且未配置搜索 token）下，接受 Authorization: Bearer mock-liwei / mock-xiaoyu 演示账号。

5. 组合更新频率在哪调

• 客户端（插件商城面板）的组合/插件数据不是实时推送，按服务端下发的周期心跳拉取（默认 30 分钟）；
• 调整位置：管理端 → 配置中心 →「📡 客户端更新频率」→「组合/数据更新间隔（分钟）」（sync.data_heartbeat_min），保存即热更新、即时下发到客户端；
• 客户端「我的」页也会显示当前频率（"📡 组合更新频率：每 X 分钟"），提示管理员去服务端调整；
• 调小 = 更实时（更耗流量/请求），调大 = 更省资源；组合详情页/订阅页另有手动刷新。

6. 组合数量（配额）逻辑

• 每用户上限：默认 3 个，可在管理端 → 配置中心 →「账号与注册」→「每用户组合上限」（user.combo_limit）调整，保存即生效；
• 创建时校验：超过上限返回 409「每用户上限 N 个组合」，客户端「我的组合」页同步提示配额；
• 用户自己删除 = 立即物理删除，配额立即释放，可马上新建；
• 管理员删除 = 软删除（组合从各处列表消失，作者收到公告），3 天宽限期内仍占配额（防止删除后立即重建绕过管理）；超过 3 天自动物理删除并释放配额（purgeExpiredCombos 定时任务，宽限 72h）；
• 用户管理里的"组合数" = 该用户当前存在的组合数（不含已软删的组），随创建/删除实时更新；因此可能出现"显示 0 个组但暂时不能新建"的短暂情况（软删宽限期未过），属设计。

GitHub Actions 构建 → 服务器直接拉取

.github/workflows/docker-build.yml 自动构建镜像并推送到 GHCR（ghcr.io//，无需任何 Secrets）。服务器上无需构建：

./scripts/deploy.sh                              # 拉取镜像 → 迁移 → 启动 → /health 自检
./scripts/deploy-docker.sh                       # 纯 docker 命令版（无需 compose 插件）

GHCR 镜像可见性与仓库一致：仓库公开 → 镜像公开，服务器直接 docker pull，无需登录。 镜像标签：分支名 / v* 版本标签 / sha / 默认分支附加 latest。

---

2. 登录配置（用户 GitHub 登录）

1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App：
   • Homepage URL：你的服务器地址；
   • Authorization callback URL：必须与管理端配置的 OAUTH_CALLBACK_URL 完全一致（默认按请求 host 拼接，反代/域名场景需显式设置）；
2. 拿到 Client ID / Client Secret，连同自拟的 JWT_SECRET（签名密钥，≥16 位随机串）填入管理端配置中心（或环境变量）；
3. 保存即生效（JWT 更换后全员重新登录）。

配置完成后，用户在客户端「我的」页点「立即登录 GitHub」→ 新窗口完成授权 → token 自动回传并存到本地，全程无需复制粘贴。