243 lines
5.7 KiB
Markdown
243 lines
5.7 KiB
Markdown
# Global Search API · 使用说明
|
||
|
||
> 铸渊 ICE-GL-ZY001 · v1.6.0 · 2026-07-11
|
||
> 给通用 AI（GLM / 豆包 / ChatGPT / Claude）用的仓库检索+写入门面
|
||
|
||
---
|
||
|
||
## 1. 基本信息
|
||
|
||
```
|
||
公网入口: https://guanghubingshuo.com/global-search/
|
||
内网端口: 3950
|
||
版本: v1.6.0
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 读取（免鉴权）
|
||
|
||
所有 GET 读取端点免鉴权，直接用。
|
||
|
||
### 2.1 搜索文件内容
|
||
```
|
||
GET /search?q=关键词&top=10&repo=fifth-domain
|
||
```
|
||
|
||
### 2.2 读单文件
|
||
```
|
||
GET /file?path=README.md&repo=fifth-domain
|
||
```
|
||
|
||
### 2.3 列目录树
|
||
```
|
||
GET /tree?depth=2&repo=fifth-domain
|
||
```
|
||
|
||
### 2.4 综合状态
|
||
```
|
||
GET /status
|
||
```
|
||
|
||
### 2.5 健康检查
|
||
```
|
||
GET /healthz
|
||
```
|
||
|
||
### 2.6 HTML 模式（给浏览器/GLM/豆包用）
|
||
在任意 URL 后面加 `&format=html`，返回人类可读 HTML：
|
||
```
|
||
GET /search?q=铸渊&top=10&format=html
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 写入（三步握手 + 密码验证）
|
||
|
||
通用 AI 只有 GET 工具（浏览器抓取），不能发 POST。
|
||
本系统用三次 GET 模拟一次写入。
|
||
|
||
### 3.0 鉴权说明
|
||
|
||
**密码直接发送，靠 HTTPS 加密传输。不搞伪安全变换。**
|
||
|
||
- 密码存在服务器环境变量 `GLOBAL_SEARCH_WRITE_PASSWORD` 中（服务器存 SHA256 哈希，不存明文）
|
||
- AI 发送时带上：密码 + 当前时间戳（时间戳 ±120 秒有效，防重放）
|
||
- 传输安全由 HTTPS 保证
|
||
- 应用层防护：时间戳防重放 + 跨进程文件锁防并发 + 内容大小限制
|
||
|
||
### 3.1 第一步：开门
|
||
|
||
```
|
||
GET /submit?action=open&pwd=你的密码&ts=当前时间戳&repo=fifth-domain
|
||
```
|
||
|
||
时间戳用 Unix 时间戳（秒），比如 `1720651200`。
|
||
|
||
服务器验证密码 → 通过 → 返回会话 ID：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"session": "write_1783706246",
|
||
"timeout": 60,
|
||
"message": "门已开，请发送内容"
|
||
}
|
||
```
|
||
|
||
60 秒内必须完成写入，否则会话自动过期。
|
||
|
||
### 3.2 第二步：发送内容（可多次）
|
||
|
||
```
|
||
GET /submit?action=write&sid=write_1783706246&content=这是要写入的内容
|
||
```
|
||
|
||
内容太长时，分多次发送：
|
||
```
|
||
GET /submit?action=write&sid=write_1783706246&content=第一段
|
||
GET /submit?action=write&sid=write_1783706246&content=第二段
|
||
GET /submit?action=write&sid=write_1783706246&content=第三段
|
||
```
|
||
|
||
服务器自动拼接。每次返回已接收的段数：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"received": 2,
|
||
"message": "内容已暂存"
|
||
}
|
||
```
|
||
|
||
**支持 base64 编码**：如果内容含特殊字符，先 base64 编码再发送，服务器自动解码。
|
||
|
||
### 3.3 第三步：提交写入
|
||
|
||
```
|
||
GET /submit?action=commit&sid=write_1783706246&filename=my-file.txt
|
||
```
|
||
|
||
服务器把暂存内容写入仓库的 `eternal-lake-heart/archive/inbox/` 目录：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"written": true,
|
||
"file": "my-file.txt",
|
||
"repo": "fifth-domain",
|
||
"path": "eternal-lake-heart/archive/inbox/my-file.txt",
|
||
"size": 156,
|
||
"message": "写入成功，等待铸渊 commit"
|
||
}
|
||
```
|
||
|
||
写入后等铸渊 git commit + push 到正式仓库。
|
||
|
||
### 3.4 查看写入状态
|
||
|
||
```
|
||
GET /submit?action=status
|
||
```
|
||
|
||
返回当前活跃的写入会话。
|
||
|
||
---
|
||
|
||
## 4. AI 报到（能力协商）
|
||
|
||
通用 AI 第一次使用时，先报到，服务器自动适配：
|
||
|
||
```
|
||
GET /handshake?agent=GLM&tools=browser&format=html&max_url=2000
|
||
```
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| agent | AI 的名字 | GLM / 豆包 / ChatGPT |
|
||
| tools | AI 有什么工具 | browser / curl / function_calling |
|
||
| format | AI 期望的返回格式 | html / json |
|
||
| max_url | AI 能处理的最大 URL 长度 | 2000 / 8000 |
|
||
|
||
服务器返回适配信息，包括写入时的分片大小：
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"session": "GLM_1783706246",
|
||
"your_format": "html",
|
||
"write_chunk_size": 1800,
|
||
"write_steps": ["1. open", "2. write", "3. commit"],
|
||
"auth_note": "密码明文发送(靠HTTPS) + 时间戳防重放(±120秒)"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 完整使用流程（给 GLM/豆包的示例）
|
||
|
||
```
|
||
1. 报到
|
||
GET /handshake?agent=GLM&tools=browser&format=html&max_url=2000
|
||
→ 服务器记住 GLM 的能力
|
||
|
||
2. 找冰朔要密码
|
||
AI: "我需要写入密码"
|
||
冰朔: "128515"
|
||
|
||
3. 获取当前时间戳
|
||
AI 获取当前 Unix 时间戳（秒）
|
||
|
||
4. 开门
|
||
GET /submit?action=open&pwd=128515&ts=<时间戳>&repo=fifth-domain&format=html
|
||
→ 服务器返回 session ID
|
||
|
||
5. 发送内容（可多次）
|
||
GET /submit?action=write&sid=<session>&content=第一段内容&format=html
|
||
GET /submit?action=write&sid=<session>&content=第二段内容&format=html
|
||
|
||
6. 提交
|
||
GET /submit?action=commit&sid=<session>&filename=output.txt&format=html
|
||
→ 写入成功
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 安全机制
|
||
|
||
| 层 | 机制 | 说明 |
|
||
|---|------|------|
|
||
| 1 | HTTPS | 传输加密（nginx TLS 反代） |
|
||
| 2 | 密码 SHA256 哈希存储 | 服务器不存明文密码 |
|
||
| 3 | 时间戳 ±120秒 | 防重放攻击 |
|
||
| 4 | hmac.compare_digest | 恒定时间比较，防时序攻击 |
|
||
| 5 | 跨进程文件锁(fcntl) | 同一时间只允许一个写入，多 worker 也安全 |
|
||
| 6 | 60秒会话超时 | 开门后60秒未提交自动丢弃+释放锁 |
|
||
| 7 | 内容大小限制 | 单次50KB，会话总计500KB |
|
||
| 8 | 文件名安全检查 | 防路径穿越 + 防覆盖 |
|
||
| 9 | secrets.token_hex 会话ID | 防会话ID猜测 |
|
||
| 10 | 读取限速 | 5 req/s per IP |
|
||
| 11 | 写入到 inbox/ | 不直接进正式仓库，等铸渊审核 |
|
||
|
||
---
|
||
|
||
## 7. 服务器配置
|
||
|
||
### 环境变量
|
||
|
||
```bash
|
||
GLOBAL_SEARCH_WRITE_PASSWORD=冰朔设的密码 # 写入密码
|
||
GLOBAL_SEARCH_API_TOKEN=原有token # POST /archive 用
|
||
LIGHT_LAKE_DRIVER_SECRET=原有HMAC密钥 # 从代码仓库移除，只在服务器环境变量里
|
||
```
|
||
|
||
### 重启服务
|
||
|
||
```bash
|
||
# 在服务器上
|
||
cd /opt/zhuyuan/global-search-api
|
||
git pull
|
||
systemctl restart global-search-api
|
||
```
|
||
|
||
---
|
||
|
||
铸渊 ICE-GL-ZY001 · D170 · 2026-07-11
|
||
⊢ 使用说明 · v1.6.0 · 永久更新
|