110 lines
2.4 KiB
Markdown
110 lines
2.4 KiB
Markdown
# 重建触发与错误码约定
|
||
|
||
本文档定义仓库对外提供的统一重建入口，供 AstrBot、cron 或手工执行复用。
|
||
|
||
## 统一入口
|
||
|
||
```bash
|
||
npm run rebuild
|
||
```
|
||
|
||
该命令会顺序执行：
|
||
|
||
1. `npm run content:sync`
|
||
2. `npm run build`
|
||
|
||
当前还不包含部署步骤；后续如接入部署，可继续扩展到同一入口里。
|
||
|
||
## 适合 AstrBot 的调用方式
|
||
|
||
AstrBot 只需要做三件事：
|
||
|
||
1. 定时触发 `npm run rebuild`
|
||
2. 读取进程退出码
|
||
3. 从输出中提取 `REBUILD_RESULT ...` 这一行，作为结构化结果
|
||
|
||
推荐通知内容：
|
||
|
||
- 成功：开始时间、结束时间、总耗时
|
||
- 失败：失败阶段、错误码、错误符号、最后几行日志
|
||
|
||
## 结构化输出
|
||
|
||
命令结束前会输出一行 JSON：
|
||
|
||
```text
|
||
REBUILD_RESULT {"ok":true,"stage":"build","code":0,"symbol":"SUCCESS",...}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `ok`: 是否成功
|
||
- `stage`: 失败或结束所在阶段，当前可能为 `sync` / `build` / `bootstrap`
|
||
- `code`: 退出码
|
||
- `symbol`: 退出码对应的文本符号
|
||
- `startedAt`: 整体开始时间
|
||
- `finishedAt`: 整体结束时间
|
||
- `durationMs`: 整体耗时
|
||
- `failedStepDurationMs`: 当前失败步骤耗时；成功时为最后一步耗时
|
||
- `logTail`: 最后若干行日志，便于 AstrBot 通知时直接带上排障信息
|
||
|
||
## 错误码
|
||
|
||
### 成功
|
||
|
||
| Code | Symbol | 含义 |
|
||
|------|--------|------|
|
||
| 0 | `SUCCESS` | 全部成功 |
|
||
|
||
### 同步阶段
|
||
|
||
| Code | Symbol | 含义 |
|
||
|------|--------|------|
|
||
| 10 | `SYNC_FAILED` | 通用同步失败 |
|
||
| 11 | `GITEA_SYNC_FAILED` | Gitea 同步失败 |
|
||
| 12 | `SEAFILE_SYNC_FAILED` | Seafile 同步失败 |
|
||
| 13 | `SCHEMA_VALIDATION_FAILED` | JSON/Schema 校验失败 |
|
||
|
||
### 构建阶段
|
||
|
||
| Code | Symbol | 含义 |
|
||
|------|--------|------|
|
||
| 20 | `BUILD_FAILED` | Astro 构建失败 |
|
||
|
||
### 部署阶段（预留）
|
||
|
||
| Code | Symbol | 含义 |
|
||
|------|--------|------|
|
||
| 30 | `DEPLOY_FAILED` | 静态产物部署失败 |
|
||
|
||
### 运行阶段
|
||
|
||
| Code | Symbol | 含义 |
|
||
|------|--------|------|
|
||
| 40 | `CONFIG_INVALID` | 运行环境缺少必要命令或配置异常 |
|
||
| 50 | `UNKNOWN_ERROR` | 未归类异常 |
|
||
|
||
## 手动补跑
|
||
|
||
本地或服务器上都可以直接执行：
|
||
|
||
```bash
|
||
npm run rebuild
|
||
```
|
||
|
||
如果只是想单独排查同步阶段，也可以先运行：
|
||
|
||
```bash
|
||
npm run content:sync
|
||
```
|
||
|
||
## 建议的 AstrBot 判定逻辑
|
||
|
||
- 退出码 `0`：发送成功通知
|
||
- 非 `0`：发送失败告警
|
||
- 优先展示：
|
||
- `symbol`
|
||
- `stage`
|
||
- `code`
|
||
- `logTail`
|