管理后台 API
管理前端位于相邻的 mynote-admin 项目。管理 API 和现有 /v1 同步 API 由同一个服务提供，共享 SQLite 和对象存储。
服务配置
使用 Node.js 24，并在部署前执行 npm ci 和 npm run build。
| 变量 | 用途 |
|---|---|
MYNOTE_ADMIN_USERNAME |
独立管理员用户名 |
MYNOTE_ADMIN_PASSWORD_HASH |
scripts/admin-password-hash.ts 从 stdin 生成的 scrypt salt:hash |
MYNOTE_ADMIN_ORIGIN |
正式后台完整 origin，例如 https://admin.example.com，不带尾部斜杠 |
用户名与哈希必须同时配置；完全未配置时管理功能关闭，管理接口返回 503。配置错误会阻止服务启动。修改配置后必须重启同步服务。
生成哈希时从 stdin 输入至少 12 个字符的密码，不把密码放在命令参数中。管理前端 README 提供 zsh 隐藏输入和本地启动示例。
接口
| 方法 | 路径 | 返回 |
|---|---|---|
| POST | /admin/v1/login |
接收 { username, password }，返回 { username }，设置会话 Cookie |
| GET | /admin/v1/session |
{ username } |
| POST | /admin/v1/logout |
撤销会话并清除 Cookie |
| GET | /admin/v1/overview |
与现有 store.metrics 相同的计数 |
| GET | /admin/v1/accounts?page=1&pageSize=20 |
{ items, total, page, pageSize } |
| GET | /admin/v1/libraries?page=1&pageSize=20 |
{ items, total, page, pageSize } |
分页大小范围 1–100，页码范围 1–1000000，按创建时间倒序、ID 升序稳定排序。列表只返回明确列出的非凭据字段。设备计数包含已退出设备，存储对象为账号级对象记录数。
身份与安全边界
- 普通用户 Bearer Token 无法访问管理 API；管理员 Cookie 无法访问用户同步 API。
- 管理员配置与已有
/metrics管理令牌独立。 - 每个登录请求最多 4 KiB；每个连接来源每分钟最多 5 次尝试。
- 管理写请求必须带匹配的 Origin，包括登录与退出。
- 开发环境默认按请求 Host 和连接协议匹配 Origin；正式环境明确设置
MYNOTE_ADMIN_ORIGIN。 - 反向代理保留 Host；未配置可信代理 IP 解析，因此代理后的登录限流按代理连接 IP 聚合。
- 密码用 scrypt 哈希校验。会话随机生成，服务端只保存 token 摘要。
- Cookie 为 HttpOnly、SameSite=Strict，路径为
/admin/v1，有效期 8 小时。 - 原生 TLS 或配置 HTTPS origin 时设置 Secure。正式部署必须使用 HTTPS。
- 会话与限流记录保存在进程内并有容量上限；重启后会话失效。当前用于单实例。
- 当前管理业务只有查询；新增写操作时需要权限校验和审计记录。
验证
node scripts/run.mts node --test test/hosted-sync-admin.test.js test/hosted-sync-http.test.js
覆盖管理员登录、Cookie 属性、越权隔离、Origin 校验、登录请求大小、字段白名单、分页边界、退出撤销、限流和未配置凭据。既有 HTTP 测试验证 client API。
列表统计与关联筛选
- 账号列表包含
libraryCount（现有仓库数）、deviceCount（未撤销设备数）和usedBytes（账号存储对象的去重字节总量，与配额接口一致）。无关联记录时返回 0。 - 笔记库列表包含
accountEmail、fileCount（未删除文件数）和versionCount（历史版本数）。 - 两个列表均支持可选的
accountId参数，精确匹配账号 ID；筛选同时影响items和total，再进行分页。未知账号返回空列表；空 ID 或超过 128 字符返回 400。 - 管理前端点击账号的仓库数量跳到
/libraries?accountId=...，点击仓库所属账号跳到/accounts?accountId=...。筛选和分页保存在 URL 中，支持刷新、浏览器前进后退和复制链接。 - 仓库对象可能在账号内共享，因此不将账号使用空间分摊成仓库占用空间。
