# 测试环境管理

**Repository Path**: kuge/test-server

## Basic Information

- **Project Name**: 测试环境管理
- **Description**: 简易的测试环境管理，基于Openresty
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-05
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Only Server — 测试部署及环境管理

基于 OpenResty 的轻量测试部署服务器。职责明确三件事：

1. 维护应用定义（启动命令模板）
2. 接收版本包并部署，通过反向代理暴露入口
3. 管理已部署环境（启停、删除）

服务器不负责拉取 Git、构建或编译，这些由 CI 或本地构建机完成。

---

## 快速开始

### 安装 OpenResty

Ubuntu / Debian：

```bash
sudo apt update
sudo apt install -y openresty curl tar
```

其他系统见：https://openresty.org/en/linux-packages.html

### 运行安装脚本

```bash
git clone <this-repo> && cd only-server
sudo bash /setup.sh
```

安装脚本会：

1. **检查 OpenResty 是否已安装**，未安装时打印安装指引并退出
2. 检查所有必要工具（tar、find、awk 等）
3. 创建目录结构 `/srv/only-server/`
4. 安装 `deployctl`、Lua API、管理 UI
5. 安装并验证 nginx 配置
6. 重载 OpenResty

安装完成后：

| 地址 | 说明 |
|------|------|
| `http://host/a/` | 管理 UI |
| `http://host/api/` | API 文档（JSON） |
| `http://host/b/<app-id>/` | 应用固定入口（始终指向最新部署） |
| `http://host/e/<env-id>/` | 指定版本入口 |

---

## 目录布局

```
/srv/only-server/
├── admin/
│   └── index.html              管理 UI
├── apps/
│   └── <app-id>/
│       ├── app.env             应用元数据
│       ├── start_command.tpl   启动命令模板
│       └── latest_env_id       当前最新环境指针
├── bin/
│   └── deployctl               CLI 管理工具
├── environments/
│   └── <env-id>/
│       ├── artifact/           原始上传包
│       ├── bin/start.sh        生成的启动脚本
│       ├── logs/stdout.log     进程标准输出
│       ├── package/            解压后的包目录
│       ├── run/app.pid         进程 PID
│       └── meta.env            环境元数据
└── lua/
    ├── api.lua                 HTTP API 实现
    └── proxy.lua               反向代理解析
```

配置文件：`/etc/only-server/deploy.env`（从 `deploy.env.sample` 复制）

---

## 应用模型

### 应用（App）

```bash
deployctl app save \
  --id my-app \
  --name "我的应用" \
  --start-cmd '{{package_dir}}/bin/my-app --bind {{bind}} --path-prefix {{entry}}'
```

启动命令支持以下变量：

| 变量 | 含义 |
|------|------|
| `{{package_file}}` | 上传包文件路径（适合单文件程序） |
| `{{package_dir}}` | 解压后目录（适合压缩包；使用时服务器会自动解压） |
| `{{package_name}}` | 上传包文件名 |
| `{{app_id}}`、`{{display_name}}` | 应用标识与名称 |
| `{{env_id}}` | 当前部署环境 ID |
| `{{git_branch}}`、`{{git_commit}}`、`{{git_commit_short}}` | Git 信息 |
| `{{version_note}}` | 版本说明 |
| `{{host}}`、`{{port}}`、`{{bind}}` | 监听地址（`bind` = `host:port`） |
| `{{entry}}` | 反向代理入口路径，例如 `/e/<env-id>` |
| `{{run_dir}}`、`{{log_dir}}` | 运行目录与日志目录 |

**注意**：启动命令必须使用 `{{package_file}}` 或 `{{package_dir}}` 之一，否则部署会被拒绝。

### 部署（Deploy）

```bash
deployctl deploy \
  --app my-app \
  --branch main \
  --commit abc1234ef \
  --note "首个测试版" \
  --package ./my-app.tar.gz
```

部署成功后：

- 新环境通过 `/e/<env-id>/` 访问
- 应用固定入口 `/b/<app-id>/` 自动更新为本次部署

### 环境管理（Env）

```bash
deployctl env list
deployctl env get    <env-id>
deployctl env enable  <env-id>
deployctl env disable <env-id>
deployctl env logs    <env-id> [--lines 100]
deployctl env delete  <env-id>
```

---

## API 参考

> 完整的机器可读文档：`GET /api/` 返回 JSON 格式的 API 说明，专为 AI Agent 设计。

所有响应为 JSON。错误响应始终包含 `error` 字段。

### 系统

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/` | API 文档（AI Agent 专用） |
| GET | `/api/status` | 系统健康：应用/环境数量、运行中环境数 |

### 应用管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/apps` | 列出所有应用 |
| POST | `/api/apps` | 创建或更新应用 |
| GET | `/api/apps/:id` | 获取单个应用（含其所有环境） |
| DELETE | `/api/apps/:id` | 删除应用（有环境时会报错） |

POST `/api/apps` 请求体：

```json
{
  "app_id": "my-app",
  "display_name": "我的应用",
  "start_command": "{{package_dir}}/bin/app --bind {{bind}} --path-prefix {{entry}}"
}
```

### 部署与环境管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/environments/deploy` | 上传包并创建新环境 |
| GET | `/api/environments` | 列出所有环境（最新在前） |
| GET | `/api/environments/:id` | 获取单个环境详情 |
| POST | `/api/environments/:id/enable` | 启动环境进程 |
| POST | `/api/environments/:id/disable` | 停止环境进程 |
| GET | `/api/environments/:id/logs` | 查看日志（`?lines=100`） |
| DELETE | `/api/environments/:id` | 停止并永久删除环境 |

部署接口 Headers：

| Header | 必须 | 说明 |
|--------|------|------|
| `Content-Type` | 是 | `application/octet-stream` |
| `X-App-Id` | 是 | 目标应用 ID |
| `X-Git-Branch` | 是 | Git 分支名 |
| `X-Git-Commit` | 是 | 完整 Git 提交 SHA |
| `X-Package-Name` | 否 | 原始包文件名（用于展示） |
| `X-Version-Note-Base64` | 否 | base64 编码的版本说明 |

部署示例（curl）：

```bash
curl -X POST http://localhost/api/environments/deploy \
  -H "X-App-Id: my-app" \
  -H "X-Git-Branch: main" \
  -H "X-Git-Commit: abc1234ef567890" \
  -H "X-Package-Name: my-app.tar.gz" \
  -H "X-Version-Note-Base64: $(echo -n '测试版' | base64)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @my-app.tar.gz
```

### 向后兼容

`/a/api/` 与 `/api/` 完全等价，保留以兼容旧工具。

---

## AI Agent 使用指南

推荐工作流：

```
1. 创建应用  POST /api/apps
2. 部署版本  POST /api/environments/deploy
3. 访问入口  GET /b/<app-id>/  或  GET /e/<env-id>/
4. 管理版本  POST /api/environments/<id>/enable|disable
5. 诊断问题  GET /api/environments/<id>/logs
```

Agent 可先 `GET /api/` 获取完整 API 文档，再按文档中的 `agent_workflow` 字段逐步执行。

---

## 本地发布脚本（Rust 项目示例）

项目根目录放一个 `publish.sh`：

```bash
#!/usr/bin/env bash
set -euo pipefail
SERVER="${DEPLOY_SERVER:-http://localhost}"
APP_ID="${1:-my-app}"
NOTE="${2:-}"

cargo build --release

BRANCH="$(git rev-parse --abbrev-ref HEAD)"
COMMIT="$(git rev-parse HEAD)"
BIN="./target/release/my-app"

curl -fsSL -X POST "${SERVER}/api/environments/deploy" \
  -H "X-App-Id: ${APP_ID}" \
  -H "X-Git-Branch: ${BRANCH}" \
  -H "X-Git-Commit: ${COMMIT}" \
  -H "X-Package-Name: my-app" \
  -H "X-Version-Note-Base64: $(printf '%s' "${NOTE}" | base64)" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@${BIN}" | jq .
```

---

## 故障排查

**部署后进程立刻退出**

```bash
deployctl env logs <env-id> --lines 80
# 或通过 API：
curl http://localhost/api/environments/<env-id>/logs?lines=80
```

**端口冲突**

`deployctl` 启动时检测端口占用，自动从 `BASE_PORT`（默认 19080）向上分配。无需手动处理。

**OpenResty 日志**

```
/srv/only-server/logs/access.log
/srv/only-server/logs/error.log
```