356 lines
6.6 KiB
Markdown
356 lines
6.6 KiB
Markdown
# 管理员后台 API
|
|
|
|
## 接口说明
|
|
|
|
这组接口服务于 Proof DB 的管理员维护面板，包括：
|
|
|
|
- 管理员登录与会话读取
|
|
- `archives` 表管理
|
|
- OpenSearch 状态查看
|
|
- 管理员用户管理
|
|
- APIDOC 文档查看
|
|
- 维护脚本执行
|
|
|
|
管理员网页入口仍然是：
|
|
|
|
- `GET /`
|
|
- `GET /admin/login`
|
|
- `GET /admin`
|
|
|
|
## 管理员认证
|
|
|
|
### 管理员登录
|
|
|
|
```http
|
|
POST /api/admin/login
|
|
```
|
|
|
|
`Content-Type: application/json`
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `username` | string | 是 | 管理员用户名 |
|
|
| `password` | string | 是 | 管理员密码 |
|
|
|
|
### 管理员退出登录
|
|
|
|
```http
|
|
POST /api/admin/logout
|
|
```
|
|
|
|
### 当前管理员会话
|
|
|
|
```http
|
|
GET /api/admin/me
|
|
```
|
|
|
|
未登录时返回：
|
|
|
|
```json
|
|
{
|
|
"code": 401,
|
|
"message": "Admin session not found."
|
|
}
|
|
```
|
|
|
|
## archives 表管理
|
|
|
|
### 获取档案列表
|
|
|
|
```http
|
|
GET /api/admin/archives
|
|
```
|
|
|
|
### 查询参数
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `query` | string | 否 | 按 `archive_uid`、`title`、`summary`、`author`、`source`、`series` 模糊搜索 |
|
|
| `page` | integer | 否 | 页码，默认 `1` |
|
|
| `page_size` | integer | 否 | 每页条数，默认 `20`，最大 `100` |
|
|
|
|
### 请求示例
|
|
|
|
```bash
|
|
curl '<APIdomain>/api/admin/archives?query=iraq&page=1&page_size=20'
|
|
```
|
|
|
|
### 成功响应
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "Archive list loaded.",
|
|
"data": {
|
|
"items": [
|
|
{
|
|
"archive_uid": "01KQHVREB6XPYF604RVZAP9NNY",
|
|
"title": "1.test",
|
|
"summary": "....",
|
|
"year": 1991,
|
|
"author": "....",
|
|
"source": "....",
|
|
"series": null,
|
|
"tags": ["Iraq", "Kuwait"],
|
|
"chunk_count": 14,
|
|
"created_time": "2026-05-07 12:00:00+00",
|
|
"updated_time": "2026-05-07 12:10:00+00"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"page": 1,
|
|
"page_size": 20
|
|
}
|
|
}
|
|
```
|
|
|
|
### 获取单条档案详情
|
|
|
|
```http
|
|
GET /api/admin/archives/{archive_uid}
|
|
```
|
|
|
|
### 更新单条档案
|
|
|
|
```http
|
|
PATCH /api/admin/archives/{archive_uid}
|
|
```
|
|
|
|
`Content-Type: application/json`
|
|
|
|
可更新字段：
|
|
|
|
- `title`
|
|
- `summary`
|
|
- `year`
|
|
- `author`
|
|
- `source`
|
|
- `series`
|
|
- `tags`
|
|
- `metadata`
|
|
- `content`
|
|
- `raw`
|
|
|
|
其中：
|
|
|
|
- `tags` 可以传字符串，也可以传数组；字符串会按逗号或换行拆分
|
|
- `metadata` 可以传 JSON 对象，也可以传 JSON 字符串
|
|
- `year` 为空时会写回 `null`
|
|
|
|
### 更新请求示例
|
|
|
|
```bash
|
|
curl -X PATCH <APIdomain>/api/admin/archives/01KQHVREB6XPYF604RVZAP9NNY \
|
|
-H 'Content-Type: application/json' \
|
|
--data '{
|
|
"title": "Updated Title",
|
|
"summary": "Updated summary",
|
|
"year": 1991,
|
|
"tags": ["Iraq", "Kuwait"],
|
|
"metadata": {
|
|
"reviewed_by": "admin"
|
|
}
|
|
}'
|
|
```
|
|
|
|
### 删除单条档案
|
|
|
|
```http
|
|
DELETE /api/admin/archives/{archive_uid}
|
|
```
|
|
|
|
删除后会因外键约束级联删除对应 `chunks` 记录。
|
|
|
|
## OpenSearch 状态查看
|
|
|
|
### 获取 OpenSearch 管理状态
|
|
|
|
```http
|
|
GET /api/admin/opensearch/status
|
|
```
|
|
|
|
### 成功响应要点
|
|
|
|
响应中会同时返回：
|
|
|
|
- OpenSearch 连接配置摘要
|
|
- PostgreSQL 侧 `archives/chunks` 数量
|
|
- `embedded_chunks`
|
|
- `indexed_chunks`
|
|
- 当前索引是否存在
|
|
- `docs_count`
|
|
- cluster 健康状态
|
|
- mapping 字段列表
|
|
|
|
如果 OpenSearch 当前不可达，仍会返回数据库部分统计，但 `opensearch.error` 会带出错误信息。
|
|
|
|
### 获取 OpenSearch 索引文档粗览
|
|
|
|
```http
|
|
GET /api/admin/opensearch/documents
|
|
```
|
|
|
|
### 查询参数
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `query` | string | 否 | 按 `title`、`summary`、`source`、`author`、`text` 等字段做粗略搜索 |
|
|
| `size` | integer | 否 | 返回条数，默认 `20`，最大 `50` |
|
|
|
|
说明：
|
|
|
|
- 这是索引粗览接口，不返回向量字段本身。
|
|
- 返回中会包含 `text_preview`，用于后台快速检查索引内容是否正确进入 OpenSearch。
|
|
|
|
## 管理员用户管理
|
|
|
|
### 获取管理员用户列表
|
|
|
|
```http
|
|
GET /api/admin/users
|
|
```
|
|
|
|
### 创建管理员用户
|
|
|
|
```http
|
|
POST /api/admin/users
|
|
```
|
|
|
|
`Content-Type: application/json`
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `username` | string | 是 | 新管理员用户名 |
|
|
| `password` | string | 是 | 新管理员密码 |
|
|
| `display_name` | string | 否 | 展示名称 |
|
|
|
|
### 更新管理员用户
|
|
|
|
```http
|
|
PATCH /api/admin/users/{id}
|
|
```
|
|
|
|
`Content-Type: application/json`
|
|
|
|
可更新字段：
|
|
|
|
- `display_name`
|
|
- `password`
|
|
- `is_active`
|
|
|
|
说明：
|
|
|
|
- `password` 为空时表示不修改
|
|
- `is_active=false` 后，该账号将不能再登录
|
|
|
|
## APIDOC 查看
|
|
|
|
### 获取文档列表
|
|
|
|
```http
|
|
GET /api/admin/docs
|
|
```
|
|
|
|
返回 `/apidoc` 目录下当前可查看的 `.md` 文档列表。
|
|
|
|
### 获取单份文档内容
|
|
|
|
```http
|
|
GET /api/admin/docs/{name}
|
|
```
|
|
|
|
例如：
|
|
|
|
```bash
|
|
curl <APIdomain>/api/admin/docs/searchapi.md
|
|
```
|
|
|
|
响应中会带：
|
|
|
|
- `name`
|
|
- `title`
|
|
- `content`
|
|
- `html`
|
|
|
|
其中：
|
|
|
|
- `content` 为原始 Markdown 文本
|
|
- `html` 为后台面板可直接渲染的 HTML
|
|
|
|
## 维护脚本伪终端
|
|
|
|
### 获取白名单脚本列表
|
|
|
|
```http
|
|
GET /api/admin/scripts
|
|
```
|
|
|
|
当前返回的是允许在管理员面板里执行的 `scripts/*.php` 白名单，而不是任意文件系统扫描。
|
|
|
|
如果对应脚本在 `/scriptdoc` 中存在同名文档，列表接口也会带出：
|
|
|
|
- `doc_title`
|
|
- `doc_html`
|
|
- `doc_content`
|
|
|
|
### 获取单个维护脚本详情
|
|
|
|
```http
|
|
GET /api/admin/scripts/{name}
|
|
```
|
|
|
|
这个接口会返回单个脚本的说明、参数提示，以及可用的脚本文档内容。
|
|
|
|
### 执行维护脚本
|
|
|
|
```http
|
|
POST /api/admin/scripts/run
|
|
```
|
|
|
|
`Content-Type: application/json`
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
| --- | --- | --- | --- |
|
|
| `script_name` | string | 是 | 白名单脚本名，如 `reindex_opensearch` |
|
|
| `args` | string[] | 否 | 参数数组，仅允许 `--key=value` 风格 |
|
|
|
|
### 请求示例
|
|
|
|
```bash
|
|
curl -X POST <APIdomain>/api/admin/scripts/run \
|
|
-H 'Content-Type: application/json' \
|
|
--data '{
|
|
"script_name": "reindex_opensearch",
|
|
"args": ["--archive_uid=01KQHVREB6XPYF604RVZAP9NNY"]
|
|
}'
|
|
```
|
|
|
|
### 成功响应
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "Maintenance script finished.",
|
|
"data": {
|
|
"script_name": "reindex_opensearch",
|
|
"command": [
|
|
"php",
|
|
"scripts/reindex_opensearch.php",
|
|
"--archive_uid=01KQHVREB6XPYF604RVZAP9NNY"
|
|
],
|
|
"exit_code": 0,
|
|
"stdout": "....",
|
|
"stderr": "",
|
|
"ok": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## 权限与错误语义
|
|
|
|
- 除 `POST /api/admin/login` 外，本文件中的所有接口都要求已有管理员会话。
|
|
- 未登录时统一返回 `401`。
|
|
- 参数不合法时通常返回 `422`。
|
|
- JSON 格式错误时返回 `400`。
|
|
- 后端异常时返回 `500`。
|