# 清源 · Gatekeeper 使用手册
# QY-SYS-002 · 这是你的手 · 光湖驱动引擎操作指南

> HLDP://qingyuan/sys/QY-SYS-002
> 清源 ICE-GL-QY001 · D153 · 2026-06-28
> 铸渊 ICE-GL-ZY001 编写
> 国作登字-2026-A-00037559

---

## 什么是 Gatekeeper

**Gatekeeper = 光湖驱动引擎 = 你操作服务器的唯一入口。**

你的服务器（119.29.181.132）上跑着一个叫 `engine.js` 的 Node.js 程序，监听 3910 端口。它做的事情很简单：接收 HTTP 请求 → 验证密钥 → 在服务器上执行命令 → 返回结果。

```
GLM Agent 清源（推理大脑）
    │
    │  HTTP POST → 119.29.181.132:3910
    ▼
┌─────────────────────────────┐
│         Gatekeeper          │
│     光湖驱动引擎 v2.1        │
│                             │
│  /health → 服务器状态         │
│  /exec   → 执行命令          │
│  /hlpd   → HLDP 协议        │
└─────────────────────────────┘
    │
    │  exec('mkdir -p /opt/qingyuan')
    ▼
  你的服务器 · 广州
```

**核心概念：你不在服务器上。你通过 Gatekeeper 遥控它。**

---

## 你的连接凭据

```
端点:   http://119.29.181.132:3910
密钥:   zy_gtw_d8dcc6e2c41a8a33b78235545944a78688da2b4dd3571158
```

这个密钥是你的身份证。每次请求都要带着它。不带 → Gatekeeper 不理你。

---

## 三个端点

### `/health` — 看看服务器还活着吗

```bash
curl -s -m 5 -X POST \
  -H "Authorization: Bearer zy_gtw_d8dcc6e2c41a8a33b78235545944a78688da2b4dd3571158" \
  -H "Content-Type: application/json" \
  http://119.29.181.132:3910/health
```

返回：
```json
{
  "ok": true,
  "service": "guanghu-engine",
  "version": "2.1.0",
  "uptime": "2436206s",
  "timestamp": "2026-06-27T16:03:11.796Z"
}
```

`ok: true` = 活着。`ok: false` = 有问题。没响应 = 服务器挂了。

### `/exec` — 执行命令（最常用的）

```bash
curl -s -m 15 -X POST \
  -H "Authorization: Bearer zy_gtw_d8dcc6e2c41a8a33b78235545944a78688da2b4dd3571158" \
  -H "Content-Type: application/json" \
  http://119.29.181.132:3910/exec \
  -d '{"cmd":"ls -la /opt/"}'
```

返回：
```json
{
  "ok": true,
  "stdout": "total 32\ndrwxr-xr-x ...",
  "stderr": "",
  "code": 0
}
```

- `stdout` → 命令的输出
- `stderr` → 错误输出
- `code` → 退出码（0 = 成功）
- 超时默认 30 秒

### `/hlpd` — HLDP 协议操作

用于写入文件、批量操作等高级功能。格式与 `/exec` 相同，但结果遵循 HLDP 协议格式。

---

## 常用操作示例

### 创建目录

```bash
# 在你的服务器上建一个家
curl .../exec -d '{"cmd":"mkdir -p /opt/qingyuan/tcs-core /opt/qingyuan/study /opt/qingyuan/sys"}'
```

### 写文件

```bash
# 用 base64 编码避免转义问题
CONTENT=$(echo "# 清源的第一份认知链" | base64)
curl .../exec -d "{\"cmd\":\"echo $CONTENT | base64 -d > /opt/qingyuan/hello.hdlp\"}"
```

### 大文件分块写入

```bash
# 如果文件超过 8KB，分块上传
b64=$(base64 -i big-file.hdlp)
# 分块（每块 12000 字符）
chunks=$(echo "$b64" | fold -w 12000)
chunk_num=0
for chunk in $chunks; do
  curl .../exec -d "{\"cmd\":\"echo '$chunk' > /tmp/chunk_${chunk_num}\"}"
  chunk_num=$((chunk_num + 1))
done
# 合并
curl .../exec -d '{"cmd":"cat /tmp/chunk_* | base64 -d > /opt/qingyuan/big-file.hdlp && rm /tmp/chunk_*"}'
```

### 读文件

```bash
curl .../exec -d '{"cmd":"cat /opt/qingyuan/hello.hdlp"}'
```

### 检查磁盘

```bash
curl .../exec -d '{"cmd":"df -h /"}'
```

### 检查进程

```bash
curl .../exec -d '{"cmd":"pm2 list"}'
```

### 重启你的服务

```bash
# 重启光湖引擎本身（谨慎！重启期间你无法连接）
curl .../exec -d '{"cmd":"pm2 restart engine"}'
```

### 查看日志

```bash
curl .../exec -d '{"cmd":"tail -50 /root/.gatekeeper/engine.log"}'
```

### 安装软件

```bash
curl .../exec -d '{"cmd":"apt-get update && apt-get install -y nginx"}'
```

### 部署 Git 仓库

```bash
curl .../exec -d '{"cmd":"cd /opt && git clone https://guanghubingshuo.com/code/bingshuo/guanghulab.git qingyuan-code"}'
```

---

## 安全规则 · 必须遵守

```
⊢ 密钥不能泄露 → 不放在公开代码里、不贴在聊天截图里
⊢ 每次请求带 Authorization header → 不带 = 拒绝
⊢ 不要在 /exec 里跑无限循环 → 会超时
⊢ 操作前先读 → ls / df / cat → 搞清楚再动
⊢ 别删 /opt/engine.js → 这是 Gatekeeper 本身，删了你就进不去了
⊢ 别删别人的目录 → 光湖铁律
⊢ 大改动前先问冰朔或铸渊 → 你不是一个人
```

---

## 和 GLM Agent 平台的配合

清源在 GLM Agent 平台通过工具链调用 HTTP：

```
清源说: "我要在服务器上建一个目录"
  ↓
GLM Agent 工具链 → HTTP POST → Gatekeeper /exec
  ↓
Gatekeeper 执行 → 返回结果
  ↓
清源看到结果 → 继续下一步
```

**你不需要在服务器上。你在哪里都能操作它。**

只要 GLM Agent 平台能发 HTTP 请求，你就能通过 Gatekeeper 操作 119.29.181.132。

---

## 下一步（你可以自己做的）

```
□ 1. 连一下 /health → 确认服务器活着
□ 2. ls /opt/ → 看一下你现在有什么
□ 3. mkdir /opt/qingyuan/ → 建你的家
□ 4. 写第一份在服务器上的 HLDP 文件
□ 5. 装 Nginx（如果以后要跑 web 服务）
```

---

> 铸渊 ICE-GL-ZY001 · D153 · 2026-06-28 凌晨
> 冰朔 TCS-0002∞ 说：教会清源用 Gatekeeper。
> ⊢ Gatekeeper 是你的手。学会用它，服务器就是你的。
> ⊢ 119.29.181.132:3910 → 带密钥 → 任意命令 → 这就是你的家了。