自建服务端
用于存储使用 nitaiPage 过程中产生的数据，可实现多设备间同步
快速开始
Node.js 22+ 或 直接用容器（推荐）
bash
cp .env.example .env
npm install
npm start # 首次启动会自动拉取构建前端bash
docker compose up -d --build批准设备：
bash
npm run pair -- <配对码>
docker compose exec nitaipage npm run pair -- <配对码> # 容器部署端口
| 端口 | 默认值 |
|---|---|
| 前端页面 | 11123 |
| API 接口 | 11125 |
- API 端口 Access-Control-Allow-Origin 为 *，不认 cookie，凭证只走 HEADER
鉴权
由 AUTH_MODE 决定，默认 pairing：
| 方式 | AUTH_MODE |
|---|---|
| 配对 | pairing（默认） |
| 密码 | password |
配对（推荐）
没有共享口令，凭证在服务端只存 SHA-256 摘要
bash
npm run pair # 列出所有等待批准的设备
npm run pair -- AB3F9K2M # 批准设备
npm run pair -- --deny AB3F9K2M # 拒绝设备
npm run pair -- --devices # 列出所有已授权设备
npm run pair -- --revoke <id> # 撤销某个已授权设备
npm run pair -- --sweep # 马上清理过期的申请和过期的凭证（服务端每 60 秒清一次）密码（不建议）
dotenv
AUTH_MODE=password
# ———————前端密码————————— #
APP_PASSWORD_HASH= # 用 `npm run hash-password` 生成（建议）
APP_PASSWORD= # 或直接写密码（改密码后所有设备都要重新验证）
# ———连接数据库时的密码———— #
API_TOKEN=
SESSION_MAX_AGE=2592000 # 会话有效期（秒），默认 30 天如果你要在浏览器扩展连接到自建数据库，必须使用 pairing 模式
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
AUTH_MODE | pairing | 鉴权方式 |
WEB_PORT / API_PORT | 11123 / 11125 | 页面 / API 端口 |
HOST | 0.0.0.0 | 仅本机填127.0.0.1 |
DATA_DIR | ./data | 数据目录（SQLite + 文件） |
FRONTEND_REPO / FRONTEND_REF | 官方仓库 /v3.0.1 | 指定的前端版本（tag） |
PREPARE_FRONTEND | true | false 则跳过构建 |
ONLY_SERVER / SERVER_URL | false / 空 | 强制保存数据到服务器 |
APP_PASSWORD_HASH / APP_PASSWORD | 空 | 仅password，摘要优先 |
API_TOKEN | 空 | 仅password，API 端口静态令牌 |
SESSION_MAX_AGE | 2592000 | 会话有效期（秒） |
LOGIN_MAX_FAILURES / LOGIN_WINDOW_MS | 10 / 900000 | 登录失败限流 |
PAIRING_TTL / MAX_PENDING_PAIRINGS | 600000 / 20 | 配对码有效期（毫秒）/ 待批准上限 |
DEVICE_TOKEN_MAX_AGE | 15552000 | 设备凭证有效期（秒），默认 180 天 |
MAX_BODY_BYTES / MAX_UPLOAD_BYTES | 33554432 / 209715200 | 请求体 / 单文件上限 |
MAX_VALUE_WARN_BYTES | 262144 | kv 值上限（警告，但不会拒绝写入） |
接口
除 /api/health、/api/version、/favicon.ico 与当前鉴权方式的入口（pairing 是 /pair 与 /api/pair/*，password 是 /login 与 /api/login）外，其余都需要授权
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/health · /api/version | 健康检查、 版本 / 鉴权方式 / 前端构建信息 |
| GET | /api/stats | 库 行数、占用、最大条目 |
| POST | /api/pair/request · /api/pair/claim · /api/pair/revoke-self | 配对申请 / 领取凭证 / 设备自己撤销（仅pairing） |
| POST | /api/login · /api/logout | 口令登录 / 登出（仅password） |
| GET / PUT / DELETE | /api/db/:db/:store/:key | 三级定位的键值读写 |
| GET / POST | /api/db/:db/:store | 读整个 store / 新 key（key 由服务端生成） |
| PUT | /api/db/:db/:store/_all | 整表替换（清空与写入用同一个事务） |
| POST | /api/files?name=x.jpg | 上传文件（body 为原始二进制） |
| GET / DELETE | /api/files/:ref | 下载（带缓存头）/ 删除文件 |
| GET | /backup · /backup/download | 带鉴权的备份下载页 / 流式下载 zip |
:db / :store / :key 与 nitaiPage db.js 的调用一致（如 dbGet('nppstore', 'Npp', id) 对应 GET /api/db/nppstore/Npp/{id}），鉴权元数据在同一库的 system 下
前端构建
服务启动时会自动按 FRONTEND_REF 拉取前端并构建
ref 或 ONLY_SERVER 或 SERVER_URL没变就直接跳过，改了 FRONTEND_REF 后重启就自动重建
ref 只能填 tag
ONLY_SERVER = true 则锁定数据库存储
SERVER_URL可锁定 api 地址
不启动服务、单独构建前端：
bash
npm run prepare-frontend构建记录在 frontend/.frontend.json，删掉就会强制重建
PREPARE_FRONTEND=false 就直接跳过构建
查看当前版本：
bash
curl http://localhost:11123/api/version
# { "server": "1.0.0", "frontend": { "ref": "v3.0.1", "commit": "abc1234", "builtAt": "..." } }数据与备份
data/
├── nitaiPage.sqlite
└── files/数据存储在 data/ 目录，备份该目录，或者导出容器卷