dscs-server 0.1.3 → 0.1.5

package/README.md

@@ -2,38 +2,80 @@
 
 DSH Session CloudSync 的自部署服务端。
 
-当前版本：**0.1.3，v2-only**（`PROTOCOL_VERSION = 3`）。设备 API 只有 `/v2/*`，
-旧的 `/v1/*` 已移除；0.0.x 插件不兼容，需要 0.1.0 起的插件。
+当前发布版本：**0.1.5**（协议版本 3，设备 API 只有 `/v2/*`；数据库结构版本 6）。
 
-## 能力
+## 能做什么
 
-- `/v2/sessions` 全量快照、`/v2/changes` 增量流；
-- 会话摘要、ETag、批次条件分页；
-- 带 `Idempotency-Key` 的 append；
-- `POST /v2/blobs/batch` / `POST /v2/blobs/batch/read` 批量 blob（8 MiB / 64 条）；
-- zstd 封帧（加密前压缩）与服务端压缩状态聚合；
-- Vault 租约、append、cursor、stream。
+- **多设备接续**：把 DSH 会话同步到自己的服务器，在另一台设备继续；
+- **私有部署**：数据留在自己的机器或 NAS，不经过第三方；
+- **端到端加密**：服务端只保存不透明密文和同步所需的基本信息，看不到会话内容；
+- **弱网可用**：断点续传、批量传输、加密前压缩，网络恢复后继续；
+- **附件通道**：加密附件（图片/文件）与按批次的附件索引有独立的 blob 类型，会话移除时一并释放；插件侧接入后生效；
+- **不会互相覆盖**：同一时间只允许一台设备上传，避免多端同时写乱；
+- **设备管理**：签发/改名/吊销设备，查看最后在线时间，为设备设置颜色；
+- **会话管理**：存档、移除并释放空间、重置后重新上传、恢复存档；
+- **审计**：记录登录、设备、配额、密码和会话管理动作，不记录内容或密钥；
+- **历史与活动**：查看单个会话的变更时间线，以及全局的每日同步强度热力图。
 
 ## 安装
 
+### 一键安装（推荐）
+
+Linux / macOS：
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/xfy2412/dsh-session-cloudsync/main/scripts/install.sh -o install.sh
+less install.sh   # 建议先看一眼脚本
+sh install.sh
+```
+
+Windows PowerShell：
+
+```powershell
+irm https://raw.githubusercontent.com/xfy2412/dsh-session-cloudsync/main/scripts/install.ps1 -OutFile install.ps1
+notepad install.ps1   # 建议先看一眼脚本
+.\install.ps1
+```
+
+安装脚本会把版本装到独立目录，并可选注册 systemd 或计划任务；支持
+`--version`、`--upgrade`、`--uninstall`、`--purge` 等参数。
+
+### 手动安装
+
 ```sh
 npm i -g dscs-server
 dscs-server serve --data-dir /var/lib/dscs --host 127.0.0.1 --port 8787
 ```
 
-首次启动会在控制台打印一次性初始化密钥，同时写入数据目录的 `onboarding-code.json`。打开 `http://127.0.0.1:8787/admin` 完成管理密码、配额和设备初始化。
+首次启动会在控制台打印一次性初始化密钥，同时写入数据目录的 `onboarding-code.json`。
+打开 `http://127.0.0.1:8787/admin` 完成管理密码、配额和设备初始化。
+
+## CLI
+
+```sh
+dscs-server serve --data-dir /var/lib/dscs --host 127.0.0.1 --port 8787
+dscs-server token add laptop
+dscs-server token list
+dscs-server token revoke <deviceId>
+dscs-server admin status
+dscs-server admin reset-password --data-dir /var/lib/dscs
+printf '%s' "$NEW_PASSWORD" | dscs-server admin reset-password --data-dir /var/lib/dscs --stdin
+```
 
-Linux/macOS 也可以使用仓库的 `scripts/install.sh`；Windows 使用 `scripts/install.ps1`。安装脚本会把版本装到独立目录，并可选注册 systemd 或计划任务。
+`admin reset-password` 默认生成并打印一次随机密码；`--stdin` 读取自定义密码。
+重置后需重启 server 让旧管理会话失效；在管理台修改密码会立即失效其它会话。
 
-## 要求
+## 要求与迁移
 
 - Node.js >= 24；
 - 默认只监听 `127.0.0.1`，公网部署请放在 TLS 反代后；
-- 数据目录包含 SQLite 与 blob 文件，升级前请备份；
-- 服务端不持有明文会话内容，只存不透明密文；
-- 0.0.1 数据目录升级到 0.1.0 会迁移到 schema 4，但旧插件仍会 404；
-- 已有未压缩会话不会自动压缩；需要清空数据目录后由 0.1.0 插件全量重传；
-- 协议说明见仓库 `docs/architecture/PROTOCOL.md`。
+- 数据目录包含 SQLite、blob 文件与迁移备份，升级前请先备份；
+- 数据库结构版本 6，支持从旧版本自动迁移，迁移前会写本地备份；
+- 0.1.5 不迁移数据库，可直接回滚；旧插件不受影响（附件功能按 `/health` 的 `attachment-index` capability 门控）；
+- 旧的变更流接口已移除；0.1.0 插件不兼容，需要插件 >= 0.1.1；
+- 服务端不持有明文会话内容，只存不透明密文和同步元数据；
+- 已有未压缩会话不会自动压缩；需要清空数据目录后由插件全量重传；
+- 协议说明见 `docs/architecture/PROTOCOL.md`，错误分类见 `docs/architecture/ERRORS.md`。
 
 ## 许可证
 

package/dist/admin-password.js

@@ -0,0 +1,27 @@
+import { randomBytes } from 'node:crypto';
+import { deriveMasterKey, newSalt } from './shared/crypto.js';
+import { recordAudit } from './audit.js';
+import { isAdminInitialized, setAdminPassword } from './db.js';
+import { validateAdminPassword } from './http.js';
+export function generateAdminPassword() {
+    for(let attempt = 0; attempt < 10; attempt += 1){
+        const candidate = randomBytes(18).toString('base64url');
+        if (validateAdminPassword(candidate) === undefined) return candidate;
+    }
+    return randomBytes(18).toString('base64url') + '!aA1';
+}
+export function resetAdminPassword(db, password) {
+    if (!isAdminInitialized(db)) throw new Error('尚未初始化，请先通过 /admin 完成初始化');
+    const problem = validateAdminPassword(password);
+    if (problem !== undefined) throw new Error(problem);
+    const salt = newSalt();
+    setAdminPassword(db, deriveMasterKey(password, salt).toString('hex'), salt.toString('hex'));
+    recordAudit(db, {
+        actorKind: 'system',
+        actorId: 'cli',
+        action: 'password.reset_cli'
+    });
+}
+
+
+//# sourceURL=admin-password.ts

package/dist/audit.js

@@ -0,0 +1,73 @@
+import { DEFAULT_DATASET } from './db.js';
+function requestMeta(req) {
+    if (req === undefined) return {
+        ip: null,
+        userAgent: null
+    };
+    const forwarded = req.headers['x-forwarded-for'];
+    const first = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+    const ip = first !== undefined && first.trim() !== '' ? first.split(',')[0].trim() : req.socket.remoteAddress ?? null;
+    const agent = req.headers['user-agent'];
+    const userAgent = typeof agent === 'string' && agent !== '' ? agent.slice(0, 300) : null;
+    return {
+        ip,
+        userAgent
+    };
+}
+export function recordAudit(db, input, req) {
+    try {
+        const meta = requestMeta(req);
+        db.handle.prepare(`INSERT INTO audit_events (dataset, at, actor_kind, actor_id, action, target, detail, ip, user_agent)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(DEFAULT_DATASET, Date.now(), input.actorKind, input.actorId, input.action, input.target ?? null, input.detail === undefined ? null : JSON.stringify(input.detail), meta.ip, meta.userAgent);
+    } catch  {}
+}
+export function listAudit(db, query = {}) {
+    const limit = Math.min(200, Math.max(1, Math.trunc(query.limit ?? 50)));
+    const where = [
+        'e.dataset = ?'
+    ];
+    const params = [
+        DEFAULT_DATASET
+    ];
+    if (query.before !== undefined && Number.isSafeInteger(query.before)) {
+        where.push('e.id < ?');
+        params.push(query.before);
+    }
+    if (query.action !== undefined && query.action !== '') {
+        where.push('e.action = ?');
+        params.push(query.action);
+    }
+    params.push(limit);
+    const rows = db.handle.prepare(`SELECT e.id, e.at, e.actor_kind, e.actor_id, e.action, e.target, e.detail, e.ip, e.user_agent,
+                     d.label AS actor_label
+              FROM audit_events e
+              LEFT JOIN devices d ON d.dataset = e.dataset AND d.device_id = e.actor_id
+              WHERE ${where.join(' AND ')}
+              ORDER BY e.id DESC LIMIT ?`).all(...params);
+    const events = rows.map((row)=>({
+            id: row.id,
+            at: row.at,
+            actorKind: row.actor_kind,
+            actorId: row.actor_id,
+            actorLabel: row.actor_kind === 'admin' ? '管理台' : row.actor_kind === 'system' ? '系统' : row.actor_label ?? row.actor_id,
+            action: row.action,
+            target: row.target,
+            detail: row.detail === null ? null : parseDetail(row.detail),
+            ip: row.ip,
+            userAgent: row.user_agent
+        }));
+    return {
+        events,
+        nextBefore: rows.length === limit ? rows[rows.length - 1].id : null
+    };
+}
+function parseDetail(raw) {
+    try {
+        return JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+}
+
+
+//# sourceURL=audit.ts

package/dist/db.js

@@ -3,7 +3,7 @@ import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 export const DEFAULT_DATASET = 'default';
-export const SERVER_SCHEMA_VERSION = 4;
+export const SERVER_SCHEMA_VERSION = 6;
 const SCHEMA_VERSION = SERVER_SCHEMA_VERSION;
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS meta (
@@ -19,6 +19,7 @@ CREATE TABLE IF NOT EXISTS devices (
   created_at INTEGER NOT NULL,
   last_seen_at INTEGER,
   revoked_at INTEGER,
+  color TEXT,
   PRIMARY KEY (dataset, device_id)
 );
 
@@ -35,6 +36,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   revision INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
   deleted_at INTEGER,
+  purged_at INTEGER,
   compression TEXT NOT NULL DEFAULT 'none',
   stored_bytes INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY (dataset, session_id)
@@ -91,6 +93,55 @@ CREATE TABLE IF NOT EXISTS tombstones (
   deleted_by TEXT NOT NULL,
   PRIMARY KEY (dataset, session_id, created_at)
 );
+
+CREATE TABLE IF NOT EXISTS audit_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  dataset TEXT NOT NULL,
+  at INTEGER NOT NULL,
+  actor_kind TEXT NOT NULL,
+  actor_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  target TEXT,
+  detail TEXT,
+  ip TEXT,
+  user_agent TEXT
+);
+
+CREATE INDEX IF NOT EXISTS audit_events_by_time ON audit_events (dataset, at DESC);
+CREATE INDEX IF NOT EXISTS audit_events_by_action ON audit_events (dataset, action, at DESC);
+
+CREATE TABLE IF NOT EXISTS session_resets (
+  dataset TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  reset_at INTEGER NOT NULL,
+  expires_at INTEGER NOT NULL,
+  device_id TEXT,
+  workspace_key TEXT,
+  PRIMARY KEY (dataset, session_id)
+);
+
+CREATE TABLE IF NOT EXISTS session_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  dataset TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  at INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  device_id TEXT,
+  actor_kind TEXT NOT NULL,
+  actor_id TEXT NOT NULL DEFAULT '',
+  events INTEGER NOT NULL DEFAULT 0,
+  bytes INTEGER NOT NULL DEFAULT 0,
+  seq_from INTEGER,
+  seq_to INTEGER,
+  batch_count INTEGER NOT NULL DEFAULT 0,
+  last_seq INTEGER,
+  stored_bytes INTEGER,
+  detail TEXT
+);
+
+CREATE INDEX IF NOT EXISTS session_events_by_session ON session_events (dataset, session_id, at);
+CREATE INDEX IF NOT EXISTS session_events_by_time ON session_events (dataset, at);
 `;
 function tableExists(handle, table) {
     const row = handle.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
@@ -161,18 +212,133 @@ function ensureSessionStatsColumns(handle) {
     if (added) backfillSessionStats(handle);
     return added;
 }
+export const DEVICE_COLORS = [
+    '#5b88ff',
+    '#5ed392',
+    '#f0b64a',
+    '#c084fc',
+    '#38bdf8',
+    '#f472b6',
+    '#a3e635',
+    '#fb923c',
+    '#94a3b8',
+    '#f87171'
+];
+export function nextDeviceColor(db) {
+    const rows = db.handle.prepare('SELECT color FROM devices WHERE dataset = ? ORDER BY created_at').all(DEFAULT_DATASET);
+    const used = new Set(rows.map((row)=>row.color).filter((color)=>typeof color === 'string' && color !== ''));
+    const free = DEVICE_COLORS.find((color)=>!used.has(color));
+    return free ?? DEVICE_COLORS[rows.length % DEVICE_COLORS.length];
+}
+function backfillDeviceColors(handle) {
+    const rows = handle.prepare('SELECT device_id, color FROM devices ORDER BY created_at, device_id').all();
+    const used = new Set(rows.map((row)=>row.color).filter((color)=>typeof color === 'string' && color !== ''));
+    const update = handle.prepare('UPDATE devices SET color = ? WHERE device_id = ?');
+    let next = 0;
+    for (const row of rows){
+        if (typeof row.color === 'string' && row.color !== '') continue;
+        let color;
+        while(next < DEVICE_COLORS.length){
+            const candidate = DEVICE_COLORS[next];
+            next += 1;
+            if (candidate !== undefined && !used.has(candidate)) {
+                color = candidate;
+                break;
+            }
+        }
+        color ??= DEVICE_COLORS[next % DEVICE_COLORS.length] ?? DEVICE_COLORS[0];
+        used.add(color);
+        update.run(color, row.device_id);
+    }
+}
+function ensureDeviceColorColumn(handle) {
+    const columns = tableColumns(handle, 'devices');
+    let added = false;
+    if (!columns.has('color')) {
+        handle.exec('ALTER TABLE devices ADD COLUMN color TEXT');
+        added = true;
+    }
+    backfillDeviceColors(handle);
+    return added;
+}
+function ensureSessionLifecycleColumns(handle) {
+    const columns = tableColumns(handle, 'sessions');
+    if (columns.has('purged_at')) return false;
+    handle.exec('ALTER TABLE sessions ADD COLUMN purged_at INTEGER');
+    return true;
+}
+function ensureSessionResetColumns(handle) {
+    if (!tableExists(handle, 'session_resets')) return false;
+    const columns = tableColumns(handle, 'session_resets');
+    if (columns.has('workspace_key')) return false;
+    handle.exec('ALTER TABLE session_resets ADD COLUMN workspace_key TEXT');
+    return true;
+}
+function ensureSessionEventColumns(handle) {
+    if (!tableExists(handle, 'session_events')) return false;
+    const columns = tableColumns(handle, 'session_events');
+    if (columns.has('actor_id')) return false;
+    handle.exec("ALTER TABLE session_events ADD COLUMN actor_id TEXT NOT NULL DEFAULT ''");
+    return true;
+}
+function backfillSessionEvents(handle) {
+    const marker = handle.prepare("SELECT value FROM meta WHERE key = 'session_events_backfill'").get();
+    if (marker !== undefined) return;
+    const existing = handle.prepare('SELECT COUNT(*) AS n FROM session_events').get();
+    if (Number(existing?.n ?? 0) > 0) {
+        handle.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('session_events_backfill', '1')").run();
+        return;
+    }
+    if (!tableExists(handle, 'append_requests')) return;
+    const rows = handle.prepare(`SELECT session_id, device_id, created_at, result_json
+                              FROM append_requests WHERE dataset = ?
+                              ORDER BY session_id ASC, created_at ASC, rowid ASC`).all(DEFAULT_DATASET);
+    const state = new Map();
+    const insert = handle.prepare(`INSERT INTO session_events
+    (dataset, session_id, at, kind, device_id, actor_kind, actor_id, events, bytes, seq_from, seq_to, batch_count, last_seq, stored_bytes, detail)
+    VALUES (?, ?, ?, ?, ?, 'device', ?, ?, ?, NULL, NULL, 1, ?, ?, ?)`);
+    for (const row of rows){
+        let summary;
+        try {
+            summary = JSON.parse(row.result_json);
+        } catch  {
+            continue;
+        }
+        if (typeof summary.lastSeq !== 'number' || !Number.isSafeInteger(summary.lastSeq)) continue;
+        const storedBytes = typeof summary.storedBytes === 'number' && Number.isSafeInteger(summary.storedBytes) ? summary.storedBytes : 0;
+        const previous = state.get(row.session_id);
+        const oldSeq = previous?.seen === true ? previous.lastSeq : 0;
+        const oldBytes = previous?.seen === true ? previous.storedBytes : 0;
+        const events = Math.max(0, summary.lastSeq - oldSeq);
+        const bytes = Math.max(0, storedBytes - oldBytes);
+        insert.run(DEFAULT_DATASET, row.session_id, row.created_at, previous?.seen === true ? 'append' : 'create', row.device_id, row.device_id, events, bytes, summary.lastSeq, storedBytes, JSON.stringify({
+            backfilled: true
+        }));
+        state.set(row.session_id, {
+            lastSeq: summary.lastSeq,
+            storedBytes,
+            seen: true
+        });
+    }
+    handle.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('session_events_backfill', '1')").run();
+}
 function migrateDatabase(handle, dataDir, version) {
     if (version > SCHEMA_VERSION) {
         throw new Error(`数据库结构版本 ${version} 高于服务端支持的 ${SCHEMA_VERSION}；请升级服务端，不要降级覆盖。`);
     }
     if (version === SCHEMA_VERSION) {
         handle.exec(SCHEMA);
+        ensureDeviceColorColumn(handle);
+        ensureSessionResetColumns(handle);
+        ensureSessionEventColumns(handle);
+        backfillSessionEvents(handle);
         const columns = tableColumns(handle, 'sessions');
-        if (!columns.has('compression') || !columns.has('stored_bytes')) {
+        if (!columns.has('compression') || !columns.has('stored_bytes') || !columns.has('purged_at')) {
             backupBeforeMigration(handle, dataDir, version);
             handle.exec('BEGIN IMMEDIATE');
             try {
                 ensureSessionStatsColumns(handle);
+                ensureSessionLifecycleColumns(handle);
                 handle.exec('COMMIT');
             } catch (error) {
                 handle.exec('ROLLBACK');
@@ -198,7 +364,7 @@ function migrateDatabase(handle, dataDir, version) {
         }
         sourceVersion = 2;
     }
-    if (sourceVersion !== 2 && sourceVersion !== 3) {
+    if (sourceVersion !== 2 && sourceVersion !== 3 && sourceVersion !== 4 && sourceVersion !== 5) {
         throw new Error(`不支持的数据库结构版本 ${sourceVersion}；请使用对应版本的服务端迁移。`);
     }
     assertV2Sessions(handle);
@@ -211,6 +377,11 @@ function migrateDatabase(handle, dataDir, version) {
         }
         handle.exec(SCHEMA);
         ensureSessionStatsColumns(handle);
+        ensureDeviceColorColumn(handle);
+        ensureSessionLifecycleColumns(handle);
+        ensureSessionResetColumns(handle);
+        ensureSessionEventColumns(handle);
+        backfillSessionEvents(handle);
         handle.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
         handle.exec('COMMIT');
     } catch (error) {