---

name: 远程 description: “SSH隧道、ngrok和远程访问管理” emoji: “🌐”

远程 - 完整API参考

管理SSH隧道、ngrok暴露和对本地Clodds实例的远程访问。

---

聊天命令

创建隧道

/remote tunnel ngrok 3000                   通过ngrok暴露端口
/remote tunnel cloudflare 3000              通过Cloudflare暴露
/remote tunnel ssh 3000 user@server          SSH隧道
/remote tunnel localtunnel 3000             通过localtunnel暴露

管理隧道

/remote list                                列出活动隧道
/remote status <id>                         检查隧道健康状态
/remote url <id>                            获取隧道URL
/remote close <id>                          关闭隧道
/remote close-all                           关闭所有隧道

端口转发

/remote forward 8080:localhost:3000         本地端口转发
/remote forward remote 3000:server:80      远程端口转发

---

TypeScript API参考

创建远程管理器

import { createRemoteManager } from 'clodds/remote';

const remote = createRemoteManager({
  // ngrok认证
  ngrokAuthToken: process.env.NGROK_AUTH_TOKEN,

  // Cloudflare隧道
  cloudflareToken: process.env.CLOUDFLARE_TUNNEL_TOKEN,

  // SSH密钥
  sshKeyPath: '~/.ssh/id_rsa',

  // 自动重连
  autoReconnect: true,
  reconnectDelayMs: 5000,
});

创建ngrok隧道

const tunnel = await remote.createNgrokTunnel({
  port: 3000,
  protocol: 'http',  // 'http' | 'tcp' | 'tls'

  // 可选
  subdomain: 'my-clodds',  // 需要付费计划
  authToken: process.env.NGROK_AUTH_TOKEN,
});

console.log(`公共URL: ${tunnel.url}`);
console.log(`隧道ID: ${tunnel.id}`);

创建Cloudflare隧道

const tunnel = await remote.createCloudflareTunnel({
  port: 3000,
  hostname: 'clodds.example.com',
  token: process.env.CLOUDFLARE_TUNNEL_TOKEN,
});

console.log(`URL: ${tunnel.url}`);

创建SSH隧道

const tunnel = await remote.createSshTunnel({
  localPort: 3000,
  remoteHost: 'server.example.com',
  remotePort: 80,
  username: 'deploy',
  privateKey: fs.readFileSync('~/.ssh/id_rsa'),
});

console.log(`隧道建立`);
console.log(`通过: ssh -L 3000:localhost:80 deploy@server.example.com`访问);

列出隧道

const tunnels = remote.listTunnels();

for (const tunnel of tunnels) {
  console.log(`${tunnel.id}: ${tunnel.type}`);
  console.log(`  URL: ${tunnel.url}`);
  console.log(`  端口: ${tunnel.port}`);
  console.log(`  状态: ${tunnel.status}`);
  console.log(`  创建时间: ${tunnel.createdAt}`);
}

检查状态

const status = await remote.getStatus(tunnelId);

console.log(`状态: ${status.status}`);  // 'connected' | 'reconnecting' | 'disconnected'
console.log(`正常运行时间: ${status.uptimeMs}ms`);
console.log(`字节入: ${status.bytesIn}`);
console.log(`字节出: ${status.bytesOut}`);

关闭隧道

// 关闭单个隧道
await remote.closeTunnel(tunnelId);

// 关闭所有隧道
await remote.closeAll();

事件处理程序

remote.on('connected', (tunnel) => {
  console.log(`隧道连接: ${tunnel.url}`);
});

remote.on('disconnected', (tunnel) => {
  console.log(`隧道断开: ${tunnel.id}`);
});

remote.on('error', (tunnel, error) => {
  console.error(`隧道错误: ${error.message}`);
});

---

隧道类型

类型	最适合	要求
ngrok	快速测试	免费账户
Cloudflare	生产环境	Cloudflare账户
SSH	安全访问	SSH服务器
localtunnel	免费，临时	无

---

用例

暴露Webhook端点

// 暴露本地服务器以进行Webhook测试
const tunnel = await remote.createNgrokTunnel({ port: 3000 });
console.log(`将Webhook URL设置为: ${tunnel.url}/webhooks/trading-signals`);

远程机器人访问

// 在家时从手机访问机器人
const tunnel = await remote.createCloudflareTunnel({
  port: 3000,
  hostname: 'clodds.mysite.com',
});
// 现在可以通过https://clodds.mysite.com访问

---

最佳实践

1. 生产环境使用Cloudflare — 比ngrok更稳定
2. 用认证保护 — 不要无保护地暴露
3. 监控连接 — 注意断开连接
4. 关闭未使用的隧道 — 不要无限期地保持开放