92 lines
7.2 KiB
Markdown
92 lines
7.2 KiB
Markdown
---
|
||
name: update-db
|
||
description: 对 LA 生产机上的 proxy-station 数据做规范化变更——增删节点、导入分享链接、调整策略组与成员、规则、规则集引用、订阅 token、Surge 设置段落。凡是用户要动线上数据的（「线上加/删个节点」「把这个组改成 url-test」「调一下规则」「建个订阅 token」「删掉那个 token」「改下生产上的设置」），都用这个 Skill，即使没提到「数据库」三个字。它只改数据不碰代码：代码更新与部署归 deploy Skill。
|
||
---
|
||
|
||
# 变更 proxy-station 生产数据
|
||
|
||
线上数据（节点、策略组、规则、token、设置）住在 la 机的 SQLite（`/opt/proxy-station/data/proxy-station.db`），由常驻的 `proxy-station` 服务直连。本 Skill 的做法是：**走服务自己的管理 API 做变更，变更前用 sqlite3 在线备份做快照**，不直接写库、不重启服务。
|
||
|
||
## 为什么必须走 API，不能直写 SQLite
|
||
|
||
API 不是简单转发，直写会绕过它的全部防护：
|
||
|
||
- zod 校验拦住坏数据（VMess 必有 UUID、WS 必有 path、SS 必有 method）
|
||
- 节点名唯一冲突返回 409；规则的 policy 必须指向存在的组或内置策略，否则规则整条失效
|
||
- 策略组改名会级联更新引用它的组成员与规则；members 是「整组替换」语义，API 帮你做对
|
||
- 订阅 token 由 crypto 随机生成、常量时间比对——手工 INSERT 塞进 null 或坏格式，`/sub` 全部当场 500
|
||
|
||
生成器每次请求实时读库，**API 改完订阅即刻生效**，不需要重启服务。直接动 SQLite 文件仅限两种只读场景：`api.sh counts` 的行数盘点，以及从备份快照里查旧值。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
bash .claude/skills/update-db/scripts/api.sh api GET /api/nodes
|
||
bash .claude/skills/update-db/scripts/api.sh api POST /api/nodes '{"name":"…","protocol":"…",…}'
|
||
bash .claude/skills/update-db/scripts/api.sh api GET /sub/<token>/clash # 拉订阅做校验（公开端点）
|
||
bash .claude/skills/update-db/scripts/api.sh backup <context> # context 用小写连字符 slug，如 add-jp-hy2
|
||
bash .claude/skills/update-db/scripts/api.sh counts
|
||
bash .claude/skills/update-db/scripts/api.sh health
|
||
```
|
||
|
||
- `api` 经 ssh 在**远端本机回环**调接口：`ADMIN_TOKEN` 只在远端 `/etc/proxy-station/env` 里展开，不经本地 shell、不落对话记录；JSON 走 stdin，无需转义
|
||
- 响应末尾带 `__HTTP_STATUS:200__` 一行。**非 2xx 时先读响应体里的错误信息再决定下一步**，不要盲目重试；要管道给 jq 时先剥掉这行：`| sed '$d' | jq …`
|
||
- 连不上 la（解析出 198.18.x.x）是本地 fake-IP 劫持了 ssh，与远端无关，等网络恢复再试
|
||
- 环境变量可覆盖 `DEPLOY_HOST`／`PS_DATA_DIR`／`PS_ENV_FILE`，默认即生产值
|
||
|
||
## 标准流程
|
||
|
||
1. **摸现状**（只读）：`api GET /api/groups`、`/api/rules`、`/api/nodes`、`/api/tokens`，把要动的对象当前值拿到手。改组成员、调规则顺序这类「全量替换」操作，不先拿全量必出错。
|
||
2. **备份**：`api.sh backup <context>`。一个变更主题一个备份，同主题内的多条变更共用一份。备份落在远端 `data/backups/`（root 属主），不要清理。
|
||
3. **执行**：逐条调 API，每条核对 HTTP_STATUS 与返回体。某条失败就停下排查，不要跳过继续。
|
||
4. **校验**：
|
||
- `counts` 与变更前对比，行数增减要能对上意图
|
||
- `api GET` 变更对象，确认落库的是新值
|
||
- 涉及下发面的变更（节点/组/规则/token 范围）：拉一次 `api GET /sub/<token>/clash` 确认 200；本地装了 mihomo 的话，`mihomo -t -f <文件>` 是最有说服力的端到端验证
|
||
- `excluded`／`skippedRules` 只存在于生成器内部、不在 HTTP 响应里；要核对静默排除时，用 `/api/nodes` 列表对比 yaml 里的 `proxies`
|
||
5. **汇报**：向用户复述三件事——变更清单、备份文件名、校验结果。三者齐了才算完成。
|
||
|
||
## 各实体的操作要点
|
||
|
||
### 节点 `/api/nodes`
|
||
- 新节点来自分享链接：先 `POST /api/nodes/import` 带 `{"text":"…","commit":false}` 预览（返回每条的解析结果与自动去重后的名字），确认后再 `commit:true` 真正入库
|
||
- 节点名是分流的关键：必须保留出口词尾缀（客户端里没有标签，用户靠名字区分直连/WARP 线路）；地区组按名称正则收编，涉及新地区先读 `docs/ADDING-REGIONS.md`
|
||
- 临时下线用 `PATCH /:id/enabled {"enabled":false}`，不要删——IR 层会自动剔除停用节点，删了凭据就没了
|
||
- 真要删除：先 GET 全量字段向用户展示将消失的内容，确认后 DELETE
|
||
|
||
### 策略组 `/api/groups`
|
||
- `members` 是**整体替换**：GET 全量 → 改数组 → PUT 回去，别只发改动项
|
||
- 成员三态：`{kind:"node", nodeId}`／`{kind:"group", refName}`／`{kind:"builtin", refName}`
|
||
- `filterRegex` 与 `includeAllNodes` 可共存，**filterRegex 优先**（动态筛选用它，新增同地区节点自动进组）
|
||
- 改名后端会级联引用，但已导入客户端的旧组名会失配——改名前先向用户点明
|
||
- url-test／fallback 组别忘了 `testUrl`／`interval`／`tolerance`
|
||
|
||
### 规则 `/api/rules`
|
||
- 顺序由 `PUT /api/rules/reorder` 的**全量 ids 数组**决定（GET 拿现有顺序 → 调整 → 全量提交）；自定义规则置顶是既有约定
|
||
- FINAL 规则永远保留；其策略组失效时 IR 层降级 DIRECT——兜底存在，但别依赖
|
||
- 新规则的 policy 必须已存在（内置 DIRECT/REJECT… 或现有组名），后端会校验，报错就先建组
|
||
- `POST /api/rules/reset` 会重置回模板初版并**清掉全部自定义规则**——除非用户明说「重置」，否则永远不调用
|
||
|
||
### 规则集 `/api/rulesets`（只读）
|
||
- `GET /api/rulesets` 看清单，`GET /:id/content` 看自托管转换结果
|
||
- `ruleset_cache` 是 24h 缓存（etag + 陈旧回落）自动管理，不要手动碰；「改规则集」实际是改引用它的规则
|
||
|
||
### 订阅 token `/api/tokens`
|
||
- 输入 `{name, nodeIds}`：`nodeIds` 空数组 = 下发全部启用节点；非空 = 只下发这些节点（给不同设备发不同范围的入口就在这里配）
|
||
- token 值由后端随机生成，创建响应里拿一次；`lastAccessAt`／`accessCount` 可判断是否仍在被使用
|
||
- **删除 token 会即刻断供所有用它的订阅 URL**——删除前必须向用户点明后果
|
||
|
||
### 设置 `/api/settings`
|
||
- `surgeSections` 是 Surge 原文段落透传，改错直接毁掉 Surge 配置；动它之前先 GET 存档 + backup，改完拉 `/sub/<token>/surge` 全文核对
|
||
|
||
## 回滚
|
||
|
||
- 单条改错：用 API 反向改回。旧值可以从备份快照只读查出：远端 `sqlite3 data/backups/<file>.db 'SELECT …'`
|
||
- 整体回滚：`api.sh restore data/backups/<file>.db --confirm`——停服换库再拉起，订阅中断约 10–20 秒，只在用户明确要求时执行
|
||
|
||
## 边界
|
||
|
||
- 不改代码、不做部署（那是 deploy Skill 的事）；不动 nginx／证书／`ADMIN_TOKEN`／systemd 单元
|
||
- 删除类操作与 reset：先列出将删除／重置的完整清单，用户确认后再执行
|
||
- 节点凭据是真凭据：汇报里不要粘贴密码／UUID 全文，用节点名指代
|