NGS/API.md

NGS API Server

基于 ylib httpserver 的 NGS 管理 API。默认监听 0.0.0.0:15665。

内置可视化控制台目录：data/www，浏览器打开：

http://127.0.0.1:15665/

启动

./br.sh
# 或
./build/ngs
# 自定义监听
./build/ngs --listen 0.0.0.0 --port 15665

面板路径可通过环境变量覆盖：NGS_PANEL_WWW=/path/to/www。

数据存储：站点元数据、MySQL 账号/密码/权限、root 密码与监听地址保存在 SQLite：data/database.db（可用 NGS_DATABASE 覆盖）。Nginx 的 www/conf/vhost/*.conf 仍为文件。

统一响应格式：

{
  "code": 200,
  "msg": "ok",
  "data": {}
}

• code = 200 表示成功
• 失败时 code 为负数或 HTTP 语义码（如 404/405/401），msg 为错误信息

---

登录鉴权

管理面板与 /api/*（除登录相关）需登录。账号密码配置文件：

www/conf/ngs.conf

首次启动若不存在会自动生成，默认：

username=admin
password=ngsadmin

修改配置后需重启 ngs 生效。浏览器使用 Cookie ngs_session。

方法	路径	说明	Body
POST	/api/auth/login	登录	{"username":"admin","password":"..."}
POST	/api/auth/logout	退出	{}
GET	/api/auth/me	当前用户（未登录返回 401）	-

---

系统

GET /api/ping

健康检查。

GET /api/status

汇总 Nginx / Fastweb / MySQL / Redis / 网站数量状态（含各组件 conf 配置路径）。

任务队列

长任务（安装/卸载）进入后台队列，立即返回 task_id。状态持久化到 www/conf/tasks.json，日志在 www/conf/tasks/<id>.log。

方法	路径	说明
GET	/api/tasks	任务列表与 active 数量
GET	/api/tasks/log?id=&offset=	增量拉取任务日志
POST	/api/tasks/clear	清理已完成/失败任务

安装类接口响应示例：

{ "code": 200, "msg": "task queued", "data": { "task_id": "t...", "active": 1 } }

GET /api/system/metrics

当前瞬时 CPU / 内存 / 磁盘 / 网络。

GET /api/system/metrics/history

后台每 2 秒采集并写入 data/metrics.db，按时间范围查询（默认 10m）。

参数	说明
range	1m / 10m / 30m / 1h / 6h / 1d / 7d / 30d

GET /api/system/processes

列出当前系统进程（读 /proc）。

参数	说明
q	可选，按 PID / 用户 / 名称 / 运行目录 / 命令行过滤

{
  "total": 120,
  "items": [
    {
      "pid": 1,
      "ppid": 0,
      "user": "root",
      "state": "S",
      "name": "systemd",
      "cmdline": "/sbin/init",
      "cwd": "/",
      "threads": 1,
      "rss": 10485760,
      "vms": 167772160,
      "mem_percent": 0.5,
      "cpu_percent": 0.1
    }
  ]
}

WebSocket /api/shell/ws?ticket=

交互式终端。先 GET /api/shell/ticket（需登录 Cookie）拿到一次性票据，再升级 WebSocket。

• 握手：只回 101 Switching Protocols（不回 JSON body）
• 客户端 → 服务端：原始键入，或 {"type":"resize","cols":120,"rows":40}
• 服务端 → 客户端：PTY 输出（二进制帧）
• 同时最多 8 个会话；断开连接自动回收

方法	路径	说明
GET	/api/shell/ticket	签发 60s 一次性 WS ticket
WS	/api/shell/ws?ticket=	终端通道

POST /api/system/processes/kill

结束进程（默认 SIGTERM）。

{ "pid": 12345, "signal": 15, "signal_name": "TERM" }

• signal / signal_name：TERM(15) / KILL(9) / INT(2) / HUP(1)

• 拒绝 PID <= 1

  {
  "range": "10m",
  "items": [
  {
    "time_ms": 1786430100000,
    "cpu_percent": 12.5,
    "cpu_cores": 8,
    "mem_percent": 40.1,
    "mem_used": 1000,
    "mem_total": 2000,
    "disk_percent": 20.0,
    "disk_used": 100,
    "disk_total": 500,
    "net_rx_bps": 1024.5,
    "net_tx_bps": 512.0
  }
  ]
  }
  

数据保留约 30 天；长区间会自动降采样。

---

Redis

方法	路径	说明	Body
GET	/api/redis/status	状态	-
POST	/api/redis/install	源码安装	{"version":"7.2.5"}（可选）
POST	/api/redis/uninstall	卸载	-
POST	/api/redis/start	启动	-
POST	/api/redis/stop	停止	-

默认安装目录：www/software/redis。默认端口 6379，占用时回退 6380。

---

文件管理

全盘路径，根目录从 / 起。

方法	路径	说明	Body / Query
GET	/api/files/list	列目录	?path=/
POST	/api/files/mkdir	新建目录	{"path":"/tmp/a"}
POST	/api/files/write	写文本/新建文件	{"path":"/tmp/a.txt","content":"..."}
GET	/api/files/read	读文本（最大 10MB，超限拒绝）	?path=/tmp/a.txt
GET	/api/files/tail	读文件尾部（默认 256KB）	?path=/tmp/a.log&bytes=262144
POST	/api/files/rename	重命名/移动	{"from":"...","to":"..."}
POST	/api/files/delete	删除	{"path":"...","recursive":false}
POST	/api/files/upload	上传	{"path":"...","content_base64":"..."} 或 content
GET	/api/files/download	下载文件	?path=/tmp/a.txt（直接文件流）

目录删除需 recursive=true 才会递归；默认仅删空目录或文件。

在线编辑/预览使用 Monaco（VS Code 同款编辑器），仅支持 ≤10MB 文本文件；超过 10MB 不可预览、不可编辑（仍可下载）。POST /api/files/write 同样拒绝超过 10MB 的内容。

---

Nginx

方法	路径	说明	Body
GET	/api/nginx/status	状态	-
POST	/api/nginx/install	安装	{"version":"1.26.3"}（可选）
POST	/api/nginx/uninstall	卸载	-
POST	/api/nginx/start	启动	-
POST	/api/nginx/stop	停止	-
POST	/api/nginx/reload	重载配置	-
GET	/api/nginx/config	读取基础配置	-
POST	/api/nginx/config	保存基础配置并重载	见下

基础配置 Body：

{
  "worker_processes": "auto",
  "worker_connections": 1024,
  "keepalive_timeout": "65",
  "client_max_body_size": "50m",
  "gzip": false
}

保存后会写入 nginx.conf、执行配置检测；若 Nginx 正在运行则自动重载生效。

---

Fastweb

方法	路径	说明	Body
GET	/api/fastweb/status	状态	-
POST	/api/fastweb/install	安装	{"debug":false}（可选）
POST	/api/fastweb/uninstall	卸载	-

---

MySQL

方法	路径	说明	Body
GET	/api/mysql/status	状态	-
POST	/api/mysql/install	安装	{"version":"8.0.35"}（可选）
POST	/api/mysql/uninstall	卸载	-
POST	/api/mysql/start	启动	-
POST	/api/mysql/stop	停止	-
POST	/api/mysql/root/password	修改 root 密码	{"password":"..."}
GET	/api/mysql/databases	数据库列表	-
POST	/api/mysql/databases	创建数据库	{"name":"db","user":"u","password":"p"}
POST	/api/mysql/databases/drop	删除数据库	{"name":"db"}
POST	/api/mysql/databases/access	设置访问权限	见下

权限设置 Body：

{
  "name": "db",
  "mode": "local|fixed_ip|any",
  "host": "1.2.3.4"
}

• local：仅本地
• fixed_ip：固定 IP（需 host）
• any：允许外网（%）

默认 MySQL 端口：3307。

---

网站

方法	路径	说明	Body
GET	/api/websites	网站列表	-
POST	/api/websites	创建网站	见下
POST	/api/websites/update	更新域名/端口/证书	`{"name","domain"
POST	/api/websites/ssl/apply	申请 Let's Encrypt（任务队列，多域名一张证；邮箱自动生成）	{"name","domains":["a.com","www.a.com"]}
POST	/api/websites/start	启动	{"name":"demo"}
POST	/api/websites/stop	停止	{"name":"demo"}
POST	/api/websites/restart	重启	{"name":"demo"}
POST	/api/websites/delete	删除网站	{"name":"demo","delete_files":false}
GET	/api/websites/analytics	站点日志分析（SQLite 聚合）	?name=demo&range=24h（1h\|6h\|24h\|7d\|30d\|all）
GET	/api/websites/logs	访问/错误日志（每站点 SQLite）	`?name=demo&kind=access
POST	/api/websites/logs/purge	清理站点日志文件和/或日志库	{"name":"demo","files":true,"db":true}

访问日志库路径：data/log/<name>.db。表 access_log / error_log；后台从 www/log/<name>/access.log、error.log 增量入库。

access_log 主要字段：time（YYYY-MM-DD HH:MM:SS）、time_ms（毫秒时间戳）、request_time（耗时秒）、bytes_recv（接收）、bytes_sent（发送）。

delete_files=true 时同时删除 wwwroot/<name> 目录；默认 false 仅删配置并保留目录。删除站点时会移除对应 data/log/<name>.db。

创建网站 Body：

{
  "name": "demo",
  "type": "static|fastweb",
  "domain": "demo.local www.demo.local",
  "domains": ["demo.local", "www.demo.local"],
  "listen_port": 8080
}

• domain / domains 可省略，默认等于 name；支持多个，格式为 域名 或 域名:端口（默认 80）
• listen_port 可省略，由域名条目解析；未写端口时默认 80
• 网站类型仅 static / fastweb；反向代理请用站点设置中的 URL 代理（/api/websites/proxies）
• type=fastweb 时会自动探测空闲端口并生成站点配置与 / URL 代理规则
• SSL：POST /api/websites/ssl/apply 使用 Let's Encrypt（HTTP-01），域名需解析到本机且 80 端口可达

列表示例字段：name / type / domain / domains / listen_port / upstream / running / root / log_dir / access_log / error_log / log_db / log_file_bytes / log_db_bytes / log_bytes / conf / ssl_*

---

示例

curl -s http://127.0.0.1:15665/api/ping
curl -s http://127.0.0.1:15665/api/status

curl -s -X POST http://127.0.0.1:15665/api/nginx/install \
  -H 'Content-Type: application/json' -d '{}'

curl -s -X POST http://127.0.0.1:15665/api/websites \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo","type":"static","domain":"demo.local"}'

curl -s http://127.0.0.1:15665/api/websites