mirror of
https://github.com/bolucat/Archive.git
synced 2025-12-24 13:28:37 +08:00
1045 lines
32 KiB
Markdown
1045 lines
32 KiB
Markdown
# NodePass API参考
|
||
|
||
## 概述
|
||
|
||
NodePass在主控模式（Master Mode）下提供了RESTful API，使前端应用能够以编程方式进行控制和集成。本节提供API端点、集成模式和最佳实践的全面文档。
|
||
|
||
## 主控模式API
|
||
|
||
当NodePass以主控模式（`master://`）运行时，它会暴露REST API，允许前端应用：
|
||
|
||
1. 创建和管理NodePass服务器和客户端实例
|
||
2. 监控连接状态和统计信息
|
||
3. 控制运行中的实例（启动、停止、重启）
|
||
4. 配置实例自启动策略以实现自动化管理
|
||
5. 通过参数配置行为
|
||
|
||
### 基本URL
|
||
|
||
```
|
||
master://<api_addr>/<prefix>?<log>&<tls>
|
||
```
|
||
|
||
其中：
|
||
- `<api_addr>`是主控模式URL中指定的地址（例如`0.0.0.0:9090`）
|
||
- `<prefix>`是可选的API前缀（如果未指定，则使用`/api`）
|
||
|
||
### 启动主控模式
|
||
|
||
使用默认设置启动主控模式的NodePass：
|
||
|
||
```bash
|
||
nodepass "master://0.0.0.0:9090?log=info"
|
||
```
|
||
|
||
使用自定义API前缀和启用TLS：
|
||
|
||
```bash
|
||
nodepass "master://0.0.0.0:9090/admin?log=info&tls=1"
|
||
```
|
||
|
||
### 可用端点
|
||
|
||
| 端点 | 方法 | 描述 |
|
||
|----------|--------|-------------|
|
||
| `/instances` | GET | 列出所有NodePass实例 |
|
||
| `/instances` | POST | 创建新的NodePass实例 |
|
||
| `/instances/{id}` | GET | 获取特定实例的详细信息 |
|
||
| `/instances/{id}` | PATCH | 更新实例状态或控制操作 |
|
||
| `/instances/{id}` | PUT | 更新实例URL配置 |
|
||
| `/instances/{id}` | DELETE | 删除特定实例 |
|
||
| `/events` | GET | 使用SSE订阅实例事件通知 |
|
||
| `/info` | GET | 获取主控服务信息 |
|
||
| `/openapi.json` | GET | OpenAPI规范 |
|
||
| `/docs` | GET | Swagger UI文档界面 |
|
||
|
||
### API认证
|
||
|
||
NodePass主控API现在支持API Key认证，可以防止未经授权的访问。系统会在首次启动时自动生成一个API Key。
|
||
|
||
#### API Key特点
|
||
|
||
1. **自动生成**：首次启动主控模式时自动创建
|
||
2. **持久化存储**：API Key与其他实例配置一起保存在`nodepass.gob`文件中
|
||
3. **重启后保留**：重启主控后API Key保持不变
|
||
4. **选择性保护**：仅保护关键API端点，公共文档仍可访问
|
||
|
||
#### 受保护的端点
|
||
|
||
以下端点需要API Key认证：
|
||
- `/instances`（所有方法）
|
||
- `/instances/{id}`（所有方法：GET、PATCH、PUT、DELETE）
|
||
- `/events`
|
||
- `/info`
|
||
|
||
以下端点可公开访问（无需API Key）：
|
||
- `/openapi.json`
|
||
- `/docs`
|
||
|
||
#### 如何使用API Key
|
||
|
||
在API请求中包含API Key：
|
||
|
||
```javascript
|
||
// 使用API Key进行实例管理请求
|
||
async function getInstances() {
|
||
const response = await fetch(`${API_URL}/instances`, {
|
||
method: 'GET',
|
||
headers: {
|
||
'X-API-Key': 'your-api-key-here'
|
||
}
|
||
});
|
||
|
||
return await response.json();
|
||
}
|
||
```
|
||
|
||
#### 如何获取和重新生成API Key
|
||
|
||
API Key可以在系统启动日志中找到，也可以通过以下方式重新生成：
|
||
|
||
```javascript
|
||
// 重新生成API Key（需要知道当前的API Key）
|
||
async function regenerateApiKey() {
|
||
const response = await fetch(`${API_URL}/instances/${apiKeyID}`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': 'current-api-key'
|
||
},
|
||
body: JSON.stringify({ action: 'restart' })
|
||
});
|
||
|
||
const result = await response.json();
|
||
return result.url; // 新的API Key
|
||
}
|
||
```
|
||
|
||
**注意**: API Key ID 固定为 `********`（八个星号）。在内部实现中，这是一个特殊的实例ID，用于存储和管理API Key。
|
||
|
||
### 使用SSE实时事件监控
|
||
|
||
NodePass现在支持服务器发送事件(SSE)功能，用于实时监控实例状态变化。这使前端应用能够即时接收实例创建、更新和删除的通知，无需轮询。
|
||
|
||
#### 使用SSE端点
|
||
|
||
SSE端点位于：
|
||
```
|
||
GET /events
|
||
```
|
||
|
||
此端点建立持久连接，使用SSE协议格式实时传递事件。如果启用了API Key认证，需要在请求头中包含有效的API Key。
|
||
|
||
#### 事件类型
|
||
|
||
支持以下事件类型：
|
||
|
||
1. `initial` - 连接建立时发送，包含所有实例的当前状态
|
||
2. `create` - 创建新实例时发送
|
||
3. `update` - 实例更新时发送（状态变更、启动/停止操作）
|
||
4. `delete` - 实例被删除时发送
|
||
5. `shutdown` - 主控服务即将关闭时发送，通知前端应用关闭连接
|
||
6. `log` - 实例产生新日志内容时发送，包含日志文本
|
||
|
||
#### JavaScript客户端实现
|
||
|
||
以下是JavaScript前端消费SSE端点的示例：
|
||
|
||
```javascript
|
||
function connectToEventSource() {
|
||
const eventSource = new EventSource(`${API_URL}/events`, {
|
||
// 如果需要认证，原生EventSource不支持自定义请求头
|
||
// 需要使用fetch API实现自定义SSE客户端
|
||
});
|
||
|
||
// 如果使用API Key，需要使用自定义实现代替原生EventSource
|
||
// 下面是使用原生EventSource的示例
|
||
eventSource.addEventListener('instance', (event) => {
|
||
const data = JSON.parse(event.data);
|
||
|
||
switch (data.type) {
|
||
case 'initial':
|
||
console.log('初始实例状态:', data.instance);
|
||
updateInstanceUI(data.instance);
|
||
break;
|
||
case 'create':
|
||
console.log('实例已创建:', data.instance);
|
||
addInstanceToUI(data.instance);
|
||
break;
|
||
case 'update':
|
||
console.log('实例已更新:', data.instance);
|
||
updateInstanceUI(data.instance);
|
||
break;
|
||
case 'delete':
|
||
console.log('实例已删除:', data.instance);
|
||
removeInstanceFromUI(data.instance.id);
|
||
break;
|
||
case 'log':
|
||
console.log(`实例 ${data.instance.id} 日志:`, data.logs);
|
||
appendLogToInstanceUI(data.instance.id, data.logs);
|
||
break;
|
||
case 'shutdown':
|
||
console.log('主控服务即将关闭');
|
||
// 关闭事件源并显示通知
|
||
eventSource.close();
|
||
showShutdownNotification();
|
||
break;
|
||
}
|
||
});
|
||
|
||
eventSource.addEventListener('error', (error) => {
|
||
console.error('SSE连接错误:', error);
|
||
// 延迟后尝试重新连接
|
||
setTimeout(() => {
|
||
eventSource.close();
|
||
connectToEventSource();
|
||
}, 5000);
|
||
});
|
||
|
||
return eventSource;
|
||
}
|
||
|
||
// 使用API Key创建SSE连接的示例
|
||
function connectToEventSourceWithApiKey(apiKey) {
|
||
// 原生EventSource不支持自定义请求头，需要使用fetch API
|
||
fetch(`${API_URL}/events`, {
|
||
method: 'GET',
|
||
headers: {
|
||
'X-API-Key': apiKey,
|
||
'Cache-Control': 'no-cache'
|
||
}
|
||
}).then(response => {
|
||
if (!response.ok) {
|
||
throw new Error(`HTTP错误: ${response.status}`);
|
||
}
|
||
|
||
const reader = response.body.getReader();
|
||
const decoder = new TextDecoder();
|
||
let buffer = '';
|
||
|
||
function processStream() {
|
||
reader.read().then(({ value, done }) => {
|
||
if (done) {
|
||
console.log('连接已关闭');
|
||
// 尝试重新连接
|
||
setTimeout(() => connectToEventSourceWithApiKey(apiKey), 5000);
|
||
return;
|
||
}
|
||
|
||
buffer += decoder.decode(value, { stream: true });
|
||
|
||
const lines = buffer.split('\n\n');
|
||
buffer = lines.pop() || '';
|
||
|
||
for (const line of lines) {
|
||
if (line.trim() === '') continue;
|
||
|
||
const eventMatch = line.match(/^event: (.+)$/m);
|
||
const dataMatch = line.match(/^data: (.+)$/m);
|
||
|
||
if (eventMatch && dataMatch) {
|
||
const data = JSON.parse(dataMatch[1]);
|
||
// 处理事件 - 见上面的switch代码
|
||
}
|
||
}
|
||
|
||
processStream();
|
||
}).catch(error => {
|
||
console.error('读取错误:', error);
|
||
// 尝试重新连接
|
||
setTimeout(() => connectToEventSourceWithApiKey(apiKey), 5000);
|
||
});
|
||
}
|
||
|
||
processStream();
|
||
}).catch(error => {
|
||
console.error('连接错误:', error);
|
||
// 尝试重新连接
|
||
setTimeout(() => connectToEventSourceWithApiKey(apiKey), 5000);
|
||
});
|
||
}
|
||
```
|
||
|
||
#### 处理实例日志
|
||
|
||
新增的`log`事件类型允许实时接收和显示实例的日志输出。这对于监控和调试非常有用：
|
||
|
||
```javascript
|
||
// 处理日志事件
|
||
function appendLogToInstanceUI(instanceId, logText) {
|
||
// 找到或创建日志容器
|
||
let logContainer = document.getElementById(`logs-${instanceId}`);
|
||
if (!logContainer) {
|
||
logContainer = document.createElement('div');
|
||
logContainer.id = `logs-${instanceId}`;
|
||
document.getElementById('instance-container').appendChild(logContainer);
|
||
}
|
||
|
||
// 创建新的日志条目
|
||
const logEntry = document.createElement('div');
|
||
logEntry.className = 'log-entry';
|
||
|
||
// 可以在这里解析ANSI颜色代码或格式化日志
|
||
logEntry.textContent = logText;
|
||
|
||
// 添加到容器
|
||
logContainer.appendChild(logEntry);
|
||
|
||
// 滚动到最新日志
|
||
logContainer.scrollTop = logContainer.scrollHeight;
|
||
}
|
||
```
|
||
|
||
#### SSE相比轮询的优势
|
||
|
||
使用SSE监控实例状态比传统轮询提供多种优势：
|
||
|
||
1. **减少延迟**：变更实时传递
|
||
2. **减轻服务器负载**：消除不必要的轮询请求
|
||
3. **带宽效率**：只在发生变更时发送数据
|
||
4. **原生浏览器支持**：无需额外库的内置浏览器支持
|
||
5. **自动重连**：浏览器在连接丢失时自动重连
|
||
|
||
#### SSE实现的最佳实践
|
||
|
||
在前端实现SSE时：
|
||
|
||
1. **处理重连**：虽然浏览器会自动尝试重连，但应实现自定义逻辑以确保持久连接
|
||
2. **高效处理事件**：保持事件处理快速，避免UI阻塞
|
||
3. **实现回退机制**：在不支持SSE的环境中，实现轮询回退
|
||
4. **处理错误**：正确处理连接错误和断开
|
||
5. **日志管理**：为每个实例维护日志缓冲区，避免无限制增长
|
||
|
||
## 前端集成指南
|
||
|
||
在将NodePass与前端应用集成时，请考虑以下重要事项：
|
||
|
||
### 实例持久化
|
||
|
||
NodePass主控模式现在支持使用gob序列化格式进行实例持久化。实例及其状态会保存到与可执行文件相同目录下的`nodepass.gob`文件中，并在主控重启时自动恢复。
|
||
|
||
主要持久化特性：
|
||
- 实例配置自动保存到磁盘
|
||
- 实例状态（运行/停止）得到保留
|
||
- 自启动策略在主控重启间保持不变
|
||
- 流量统计数据在重启之间保持
|
||
- 启用自启动策略的实例在主控重启时自动启动
|
||
- 重启后无需手动重新注册
|
||
|
||
**注意：** 虽然实例配置现在已经持久化，前端应用仍应保留自己的实例配置记录作为备份策略。
|
||
|
||
### 实例生命周期管理
|
||
|
||
为了合理管理生命周期：
|
||
|
||
1. **创建**：存储实例配置和URL
|
||
```javascript
|
||
async function createNodePassInstance(config) {
|
||
const response = await fetch(`${API_URL}/instances`, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({
|
||
url: `server://0.0.0.0:${config.port}/${config.target}?tls=${config.tls}`
|
||
})
|
||
});
|
||
|
||
const data = await response.json();
|
||
|
||
// 根据类型为新实例配置自启动策略
|
||
if (data.success) {
|
||
const shouldAutoRestart = config.type === 'server' || config.critical === true;
|
||
await setAutoStartPolicy(data.data.id, shouldAutoRestart);
|
||
}
|
||
|
||
// 存储在前端持久化存储中
|
||
saveInstanceConfig({
|
||
id: data.data.id,
|
||
originalConfig: config,
|
||
url: data.data.url
|
||
});
|
||
|
||
return data;
|
||
}
|
||
```
|
||
|
||
2. **状态监控**：监控实例状态变化
|
||
|
||
NodePass提供两种监控实例状态的方法：
|
||
|
||
A. **使用SSE（推荐）**：通过持久连接接收实时事件
|
||
```javascript
|
||
function connectToEventSource() {
|
||
const eventSource = new EventSource(`${API_URL}/events`, {
|
||
// 如果需要认证，需要使用自定义实现
|
||
});
|
||
|
||
// 或者使用带API Key的自定义实现
|
||
// connectToEventSourceWithApiKey(apiKey);
|
||
|
||
eventSource.addEventListener('instance', (event) => {
|
||
const data = JSON.parse(event.data);
|
||
// 处理不同类型的事件：initial, create, update, delete, log
|
||
// ...处理逻辑见前面的"使用SSE实时事件监控"部分
|
||
});
|
||
|
||
// 错误处理和重连逻辑
|
||
// ...详见前面的示例
|
||
|
||
return eventSource;
|
||
}
|
||
```
|
||
|
||
B. **传统轮询（备选）**：在不支持SSE的环境中使用
|
||
```javascript
|
||
function startInstanceMonitoring(instanceId, interval = 5000) {
|
||
return setInterval(async () => {
|
||
try {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
headers: {
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
}
|
||
});
|
||
const data = await response.json();
|
||
|
||
if (data.success) {
|
||
updateInstanceStatus(instanceId, data.data.status);
|
||
updateInstanceMetrics(instanceId, {
|
||
connections: data.data.connections,
|
||
pool_size: data.data.pool_size,
|
||
uptime: data.data.uptime
|
||
});
|
||
}
|
||
} catch (error) {
|
||
markInstanceUnreachable(instanceId);
|
||
}
|
||
}, interval);
|
||
}
|
||
```
|
||
|
||
**选择建议：** 优先使用SSE方式，它提供更高效的实时监控，减轻服务器负担。仅在客户端不支持SSE或需要特定环境兼容性时使用轮询方式。
|
||
|
||
3. **实例别名管理**：为实例设置易读的名称
|
||
```javascript
|
||
// 批量设置实例别名
|
||
async function setInstanceAliases(instances) {
|
||
for (const instance of instances) {
|
||
// 根据实例类型和用途生成有意义的别名
|
||
const alias = `${instance.type}-${instance.region || 'default'}-${instance.port || 'auto'}`;
|
||
await updateInstanceAlias(instance.id, alias);
|
||
}
|
||
}
|
||
|
||
// 根据别名查找实例
|
||
async function findInstanceByAlias(targetAlias) {
|
||
const response = await fetch(`${API_URL}/instances`, {
|
||
headers: { 'X-API-Key': apiKey }
|
||
});
|
||
const data = await response.json();
|
||
|
||
if (data.success) {
|
||
return data.data.find(instance => instance.alias === targetAlias);
|
||
}
|
||
return null;
|
||
}
|
||
```
|
||
|
||
4. **控制操作**：启动、停止、重启实例
|
||
```javascript
|
||
async function controlInstance(instanceId, action) {
|
||
// action可以是: start, stop, restart
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PATCH', // 注意：API已更新为使用PATCH方法而非PUT
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({ action })
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
|
||
// 更新实例别名
|
||
async function updateInstanceAlias(instanceId, alias) {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({ alias })
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
|
||
// 更新实例URL配置
|
||
async function updateInstanceURL(instanceId, newURL) {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PUT',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({ url: newURL })
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
```
|
||
|
||
5. **自启动策略管理**：配置自动启动行为
|
||
```javascript
|
||
async function setAutoStartPolicy(instanceId, enableAutoStart) {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({ restart: enableAutoStart })
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
|
||
// 组合操作：控制实例并更新自启动策略
|
||
async function controlInstanceWithAutoStart(instanceId, action, enableAutoStart) {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({
|
||
action: action,
|
||
restart: enableAutoStart
|
||
})
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
|
||
// 组合操作：同时更新别名、控制实例和自启动策略
|
||
async function updateInstanceComplete(instanceId, alias, action, enableAutoStart) {
|
||
const response = await fetch(`${API_URL}/instances/${instanceId}`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey // 如果启用了API Key
|
||
},
|
||
body: JSON.stringify({
|
||
alias: alias,
|
||
action: action,
|
||
restart: enableAutoStart
|
||
})
|
||
});
|
||
|
||
const data = await response.json();
|
||
return data.success;
|
||
}
|
||
```
|
||
|
||
#### 自启动策略完整使用示例
|
||
|
||
以下是一个全面的示例，展示了如何在实际场景中实现自启动策略管理：
|
||
|
||
```javascript
|
||
// 场景：建立带有自启动策略的负载均衡服务器集群
|
||
async function setupServerCluster(serverConfigs) {
|
||
const clusterInstances = [];
|
||
|
||
for (const config of serverConfigs) {
|
||
try {
|
||
// 创建服务器实例
|
||
const instance = await createNodePassInstance({
|
||
type: 'server',
|
||
port: config.port,
|
||
target: config.target,
|
||
critical: config.isPrimary, // 主服务器为关键实例
|
||
tls: config.enableTLS
|
||
});
|
||
|
||
if (instance.success) {
|
||
// 设置有意义的实例别名
|
||
const alias = `${config.role}-server-${config.port}`;
|
||
await updateInstanceAlias(instance.data.id, alias);
|
||
|
||
// 根据服务器角色配置自启动策略
|
||
const autoStartPolicy = config.isPrimary || config.role === 'essential';
|
||
await setAutoStartPolicy(instance.data.id, autoStartPolicy);
|
||
|
||
// 启动实例
|
||
await controlInstance(instance.data.id, 'start');
|
||
|
||
clusterInstances.push({
|
||
id: instance.data.id,
|
||
alias: alias,
|
||
role: config.role,
|
||
autoStartEnabled: autoStartPolicy
|
||
});
|
||
|
||
console.log(`服务器 ${alias} 已创建，自启动策略: ${autoStartPolicy}`);
|
||
}
|
||
} catch (error) {
|
||
console.error(`创建服务器 ${config.role} 失败:`, error);
|
||
}
|
||
}
|
||
|
||
return clusterInstances;
|
||
}
|
||
|
||
// 监控集群健康状态并动态调整自启动策略
|
||
async function monitorClusterHealth(clusterInstances) {
|
||
const healthyInstances = [];
|
||
|
||
for (const cluster of clusterInstances) {
|
||
const instance = await fetch(`${API_URL}/instances/${cluster.id}`, {
|
||
headers: { 'X-API-Key': apiKey }
|
||
});
|
||
const data = await instance.json();
|
||
|
||
if (data.success && data.data.status === 'running') {
|
||
healthyInstances.push(cluster);
|
||
} else {
|
||
// 如果关键实例宕机，为备份实例启用自启动策略
|
||
if (cluster.role === 'primary') {
|
||
await enableBackupInstanceAutoStart(clusterInstances);
|
||
}
|
||
}
|
||
}
|
||
|
||
return healthyInstances;
|
||
}
|
||
|
||
async function enableBackupInstanceAutoStart(clusterInstances) {
|
||
const backupInstances = clusterInstances.filter(c => c.role === 'backup');
|
||
for (const backup of backupInstances) {
|
||
await setAutoStartPolicy(backup.id, true);
|
||
console.log(`已为备份实例启用自启动策略: ${backup.id}`);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 流量统计
|
||
|
||
主控API提供流量统计数据，但需要注意以下重要事项：
|
||
|
||
1. **启用调试模式**：流量统计功能仅在启用调试模式时可用。
|
||
|
||
```bash
|
||
# 启用调试模式的主控
|
||
nodepass master://0.0.0.0:10101?log=debug
|
||
```
|
||
|
||
如果未启用调试模式，API将不会收集或返回流量统计数据。
|
||
|
||
2. **基本流量指标**：NodePass周期性地提供TCP和UDP流量在入站和出站方向上的累计值，前端应用需要存储和处理这些值以获得有意义的统计信息。
|
||
```javascript
|
||
function processTrafficStats(instanceId, currentStats) {
|
||
// 存储当前时间戳
|
||
const timestamp = Date.now();
|
||
|
||
// 如果我们有该实例的前一个统计数据，计算差值
|
||
if (previousStats[instanceId]) {
|
||
const timeDiff = timestamp - previousStats[instanceId].timestamp;
|
||
const tcpInDiff = currentStats.tcp_in - previousStats[instanceId].tcp_in;
|
||
const tcpOutDiff = currentStats.tcp_out - previousStats[instanceId].tcp_out;
|
||
const udpInDiff = currentStats.udp_in - previousStats[instanceId].udp_in;
|
||
const udpOutDiff = currentStats.udp_out - previousStats[instanceId].udp_out;
|
||
|
||
// 存储历史数据用于图表展示
|
||
storeTrafficHistory(instanceId, {
|
||
timestamp,
|
||
tcp_in_rate: tcpInDiff / timeDiff * 1000, // 每秒字节数
|
||
tcp_out_rate: tcpOutDiff / timeDiff * 1000,
|
||
udp_in_rate: udpInDiff / timeDiff * 1000,
|
||
udp_out_rate: udpOutDiff / timeDiff * 1000
|
||
});
|
||
}
|
||
|
||
// 更新前一个统计数据，用于下次计算
|
||
previousStats[instanceId] = {
|
||
timestamp,
|
||
tcp_in: currentStats.tcp_in,
|
||
tcp_out: currentStats.tcp_out,
|
||
udp_in: currentStats.udp_in,
|
||
udp_out: currentStats.udp_out
|
||
};
|
||
}
|
||
```
|
||
|
||
3. **数据持久化**：由于API只提供累计值，前端必须实现适当的存储和计算逻辑
|
||
```javascript
|
||
// 前端流量历史存储结构示例
|
||
const trafficHistory = {};
|
||
|
||
function storeTrafficHistory(instanceId, metrics) {
|
||
if (!trafficHistory[instanceId]) {
|
||
trafficHistory[instanceId] = {
|
||
timestamps: [],
|
||
tcp_in_rates: [],
|
||
tcp_out_rates: [],
|
||
udp_in_rates: [],
|
||
udp_out_rates: []
|
||
};
|
||
}
|
||
|
||
trafficHistory[instanceId].timestamps.push(metrics.timestamp);
|
||
trafficHistory[instanceId].tcp_in_rates.push(metrics.tcp_in_rate);
|
||
trafficHistory[instanceId].tcp_out_rates.push(metrics.tcp_out_rate);
|
||
trafficHistory[instanceId].udp_in_rates.push(metrics.udp_in_rate);
|
||
trafficHistory[instanceId].udp_out_rates.push(metrics.udp_out_rate);
|
||
|
||
// 保持历史数据量可管理
|
||
const MAX_HISTORY = 1000;
|
||
if (trafficHistory[instanceId].timestamps.length > MAX_HISTORY) {
|
||
trafficHistory[instanceId].timestamps.shift();
|
||
trafficHistory[instanceId].tcp_in_rates.shift();
|
||
trafficHistory[instanceId].tcp_out_rates.shift();
|
||
trafficHistory[instanceId].udp_in_rates.shift();
|
||
trafficHistory[instanceId].udp_out_rates.shift();
|
||
}
|
||
}
|
||
```
|
||
|
||
### 实例ID持久化
|
||
|
||
由于NodePass现在使用gob格式持久化存储实例状态，实例ID在主控重启后**不再发生变化**。这意味着：
|
||
|
||
1. 前端应用可以安全地使用实例ID作为唯一标识符
|
||
2. 实例配置、状态和统计数据在重启后自动恢复
|
||
3. 不再需要实现实例ID变化的处理逻辑
|
||
|
||
这极大简化了前端集成，消除了以前处理实例重新创建和ID映射的复杂性。
|
||
|
||
### 自启动策略管理
|
||
|
||
NodePass现在支持为实例配置自启动策略，实现自动化实例管理并提高可靠性。自启动策略功能具备以下特性：
|
||
|
||
1. **自动实例恢复**：启用自启动策略的实例在主控服务重启时会自动启动
|
||
2. **选择性自启动**：根据实例的重要性或角色配置哪些实例应该自动启动
|
||
3. **持久化策略存储**：自启动策略在主控重启间保存和恢复
|
||
4. **细粒度控制**：每个实例都可以有自己的自启动策略设置
|
||
|
||
#### 自启动策略工作原理
|
||
|
||
- **策略分配**：每个实例都有一个`restart`布尔字段，决定其自启动行为
|
||
- **主控启动**：主控启动时，自动启动所有`restart: true`的实例
|
||
- **策略持久化**：自启动策略与其他实例数据一起保存在`nodepass.gob`文件中
|
||
- **运行时管理**：自启动策略可以在实例运行时修改
|
||
|
||
#### 自启动策略最佳实践
|
||
|
||
1. **为服务器实例启用**：服务器实例通常应启用自启动策略以确保高可用性
|
||
2. **选择性客户端自启动**：仅为关键客户端连接启用自启动策略
|
||
3. **测试场景**：为临时或测试实例禁用自启动策略
|
||
4. **负载均衡**：使用自启动策略维持最小实例数量以分配负载
|
||
|
||
```javascript
|
||
// 示例：根据实例角色配置自启动策略
|
||
async function configureAutoStartPolicies(instances) {
|
||
for (const instance of instances) {
|
||
// 为服务器和关键客户端启用自启动
|
||
const shouldAutoStart = instance.type === 'server' ||
|
||
instance.tags?.includes('critical');
|
||
|
||
await setAutoStartPolicy(instance.id, shouldAutoStart);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 实例数据结构
|
||
|
||
API响应中的实例对象包含以下字段：
|
||
|
||
```json
|
||
{
|
||
"id": "a1b2c3d4", // 实例唯一标识符
|
||
"alias": "web-server-01", // 实例别名（可选，用于显示友好名称）
|
||
"type": "server", // 实例类型：server 或 client
|
||
"status": "running", // 实例状态：running、stopped 或 error
|
||
"url": "server://...", // 实例配置URL
|
||
"restart": true, // 自启动策略
|
||
"tcprx": 1024, // TCP接收字节数
|
||
"tcptx": 2048, // TCP发送字节数
|
||
"udprx": 512, // UDP接收字节数
|
||
"udptx": 256 // UDP发送字节数
|
||
}
|
||
```
|
||
|
||
**注意：**
|
||
- `alias` 字段为可选，如果未设置则为空字符串
|
||
- 流量统计字段（tcprx、tcptx、udprx、udptx）仅在启用调试模式时有效
|
||
- `restart` 字段控制实例的自启动行为
|
||
|
||
## 系统信息端点
|
||
|
||
`/info` 端点提供了关于NodePass主控服务的系统信息。这个端点对于监控、故障排除和系统状态验证非常有用。
|
||
|
||
### 请求
|
||
|
||
```
|
||
GET /info
|
||
```
|
||
|
||
需要 API Key 认证：是
|
||
|
||
### 响应
|
||
|
||
响应包含以下系统信息字段：
|
||
|
||
```json
|
||
{
|
||
"os": "linux", // 操作系统类型
|
||
"arch": "amd64", // 系统架构
|
||
"ver": "1.2.0", // NodePass版本
|
||
"name": "example.com", // 隧道主机名
|
||
"uptime": 11525, // API运行时间（秒）
|
||
"log": "info", // 日志级别
|
||
"tls": "1", // TLS启用状态
|
||
"crt": "/path/to/cert", // 证书路径
|
||
"key": "/path/to/key" // 密钥路径
|
||
}
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
```javascript
|
||
// 获取系统信息
|
||
async function getSystemInfo() {
|
||
const response = await fetch(`${API_URL}/info`, {
|
||
method: 'GET',
|
||
headers: {
|
||
'X-API-Key': apiKey
|
||
}
|
||
});
|
||
|
||
return await response.json();
|
||
}
|
||
|
||
// 显示服务运行时间
|
||
function displayServiceUptime() {
|
||
getSystemInfo().then(info => {
|
||
console.log(`服务已运行: ${info.uptime} 秒`);
|
||
// 也可以格式化为更友好的显示
|
||
const hours = Math.floor(info.uptime / 3600);
|
||
const minutes = Math.floor((info.uptime % 3600) / 60);
|
||
const seconds = info.uptime % 60;
|
||
console.log(`服务已运行: ${hours}小时${minutes}分${seconds}秒`);
|
||
});
|
||
}
|
||
```
|
||
|
||
### 监控最佳实践
|
||
|
||
- **定期检查**：定期轮询此端点以确保服务正常运行
|
||
- **版本验证**：在部署更新后检查版本号
|
||
- **运行时间监控**：监控运行时间以检测意外重启
|
||
- **日志级别验证**：确认当前日志级别符合预期
|
||
|
||
## API端点文档
|
||
|
||
有关详细的API文档（包括请求和响应示例），请使用`/docs`端点提供的内置Swagger UI文档。这个交互式文档提供了以下全面信息：
|
||
|
||
- 可用的端点
|
||
- 必需的参数
|
||
- 响应格式
|
||
- 请求和响应示例
|
||
- 架构定义
|
||
|
||
### 访问Swagger UI
|
||
|
||
要访问Swagger UI文档：
|
||
|
||
```
|
||
http(s)://<api_addr>[<prefix>]/docs
|
||
```
|
||
|
||
例如：
|
||
```
|
||
http://localhost:9090/api/docs
|
||
```
|
||
|
||
Swagger UI提供了一种方便的方式，直接在浏览器中探索和测试API。您可以针对运行中的NodePass主控实例执行API调用，并查看实际响应。
|
||
|
||
## 完整的API参考
|
||
|
||
### 实例管理端点详细说明
|
||
|
||
#### GET /instances
|
||
- **描述**：获取所有实例列表
|
||
- **认证**：需要API Key
|
||
- **响应**：实例数组
|
||
- **示例**：
|
||
```javascript
|
||
const instances = await fetch(`${API_URL}/instances`, {
|
||
headers: { 'X-API-Key': apiKey }
|
||
});
|
||
```
|
||
|
||
#### POST /instances
|
||
- **描述**：创建新实例
|
||
- **认证**：需要API Key
|
||
- **请求体**：`{ "url": "client://或server://格式的URL" }`
|
||
- **响应**：新创建的实例对象
|
||
- **示例**：
|
||
```javascript
|
||
const newInstance = await fetch(`${API_URL}/instances`, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey
|
||
},
|
||
body: JSON.stringify({ url: 'server://0.0.0.0:8080/localhost:3000' })
|
||
});
|
||
```
|
||
|
||
#### GET /instances/{id}
|
||
- **描述**：获取特定实例详情
|
||
- **认证**：需要API Key
|
||
- **响应**：实例对象
|
||
- **示例**：
|
||
```javascript
|
||
const instance = await fetch(`${API_URL}/instances/abc123`, {
|
||
headers: { 'X-API-Key': apiKey }
|
||
});
|
||
```
|
||
|
||
#### PATCH /instances/{id}
|
||
- **描述**：更新实例状态、别名或执行控制操作
|
||
- **认证**：需要API Key
|
||
- **请求体**：`{ "alias": "新别名", "action": "start|stop|restart|reset", "restart": true|false }`
|
||
- **特点**：不中断正在运行的实例，仅更新指定字段。`action: "reset"` 可将该实例的流量统计（tcprx、tcptx、udprx、udptx）清零。
|
||
- **示例**：
|
||
```javascript
|
||
// 更新别名和自启动策略
|
||
await fetch(`${API_URL}/instances/abc123`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey
|
||
},
|
||
body: JSON.stringify({
|
||
alias: 'Web服务器',
|
||
restart: true
|
||
})
|
||
});
|
||
|
||
// 控制实例操作
|
||
await fetch(`${API_URL}/instances/abc123`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey
|
||
},
|
||
body: JSON.stringify({ action: 'restart' })
|
||
});
|
||
|
||
// 清零流量统计
|
||
await fetch(`${API_URL}/instances/abc123`, {
|
||
method: 'PATCH',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey
|
||
},
|
||
body: JSON.stringify({ action: 'reset' })
|
||
});
|
||
```
|
||
|
||
#### PUT /instances/{id}
|
||
- **描述**：完全更新实例URL配置
|
||
- **认证**：需要API Key
|
||
- **请求体**：`{ "url": "新的client://或server://格式的URL" }`
|
||
- **特点**：会重启实例。
|
||
- **限制**：API Key实例（ID为`********`）不支持此操作
|
||
- **示例**：
|
||
```javascript
|
||
// 更新实例URL
|
||
await fetch(`${API_URL}/instances/abc123`, {
|
||
method: 'PUT',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'X-API-Key': apiKey
|
||
},
|
||
body: JSON.stringify({
|
||
url: 'server://0.0.0.0:9090/localhost:8080?tls=1'
|
||
})
|
||
});
|
||
```
|
||
|
||
#### DELETE /instances/{id}
|
||
- **描述**：删除实例
|
||
- **认证**：需要API Key
|
||
- **响应**：204 No Content
|
||
- **限制**：API Key实例（ID为`********`）不可删除
|
||
- **示例**：
|
||
```javascript
|
||
await fetch(`${API_URL}/instances/abc123`, {
|
||
method: 'DELETE',
|
||
headers: { 'X-API-Key': apiKey }
|
||
});
|
||
```
|
||
|
||
### 其他端点
|
||
|
||
#### GET /events
|
||
- **描述**：建立SSE连接以接收实时事件
|
||
- **认证**：需要API Key
|
||
- **响应**：Server-Sent Events流
|
||
- **事件类型**：`initial`, `create`, `update`, `delete`, `shutdown`, `log`
|
||
|
||
#### GET /info
|
||
- **描述**：获取主控服务信息
|
||
- **认证**：需要API Key
|
||
- **响应**：包含系统信息、版本、运行时间等
|
||
|
||
#### GET /openapi.json
|
||
- **描述**：获取OpenAPI 3.1.1规范
|
||
- **认证**：无需认证
|
||
- **响应**：JSON格式的API规范
|
||
|
||
#### GET /docs
|
||
- **描述**：Swagger UI文档界面
|
||
- **认证**：无需认证
|
||
- **响应**：HTML格式的交互式文档
|
||
|
||
### 实例URL格式规范
|
||
|
||
实例URL必须遵循以下格式：
|
||
|
||
#### 服务器模式 (Server Mode)
|
||
```
|
||
server://<bind_address>:<bind_port>/<target_host>:<target_port>?<parameters>
|
||
```
|
||
|
||
示例：
|
||
- `server://0.0.0.0:8080/localhost:3000` - 在8080端口监听，转发到本地3000端口
|
||
- `server://0.0.0.0:9090/localhost:8080?tls=1` - 启用TLS的服务器
|
||
|
||
#### 客户端模式 (Client Mode)
|
||
```
|
||
client://<server_host>:<server_port>/<local_host>:<local_port>?<parameters>
|
||
```
|
||
|
||
示例：
|
||
- `client://example.com:8080/localhost:3000` - 连接到远程服务器，本地监听3000端口
|
||
- `client://vpn.example.com:443/localhost:22?tls=1` - 通过TLS连接到VPN服务器
|
||
|
||
#### 支持的参数
|
||
|
||
| 参数 | 描述 | 值 | 默认值 |
|
||
|------|------|----|----|
|
||
| `tls` | TLS加密级别 | `0`(无), `1`(自签名), `2`(证书) | `0` |
|
||
| `log` | 日志级别 | `trace`, `debug`, `info`, `warn`, `error` | `info` |
|
||
| `crt` | 证书路径 | 文件路径 | 无 |
|
||
| `key` | 私钥路径 | 文件路径 | 无 |
|