插件托管与部署

版本: 1.0
更新日期: 2026-06-16

---

部署模式对比

	托管 (managed)	自托管 (self-hosted)
谁部署	UnityAI 平台	开发者自己
代码上传	必须	可选
运行环境	平台提供 (Python/Node)	开发者自由选择
自动重启	平台负责	开发者负责
资源限制	256MB 内存 / 1hr CPU	无限制
访问地址	平台分配 localhost 端口	开发者提供 HTTPS URL
健康检查	每 5 秒（进程级）	每 5 分钟（HTTP 级）
适合场景	轻量工具、快速上架	重型服务、自主运维

---

托管模式详解

生命周期

代码上传 → 审核通过 → 用户启动时自动 spawn 进程
                         ↓
              分配随机端口 → 健康检查 → 可用
                         ↓ (crash)
              自动重启（最多 3 次，指数退避）

运行时环境

运行时	命令	环境变量
Python	python3 {entry_point}	PORT, MAIN_APP_URL
Node.js	node {entry_point}	PORT, MAIN_APP_URL

资源限制

资源	限制
内存	256MB (RLIMIT_AS)
CPU 时间	3600 秒 (RLIMIT_CPU)
子进程数	10 (Linux nproc)

process_config 示例

{
  "runtime": "python",
  "entry_point": "api/main.py",
  "port": 8000,
  "ui": {
    "type": "iframe",
    "width": 1200,
    "height": 800
  }
}

---

自托管模式详解

要求

1. 部署 HTTP(S) 服务到公网可访问地址
2. 实现 GET /health 端点（返回 2xx 即可）
3. 提交时提供 self_hosted_url
4. 生产环境必须使用 HTTPS

可选 API Key

如果你的服务需要认证：

• 提交时填写 self_hosted_api_key
• 平台使用 AES-256-GCM 加密存储
• 用户启动插件时，平台解密 Key 并透传给前端
• 前端在请求你的服务时附带此 Key

健康检查机制

平台后台 ──(每 5 分钟)──► GET {self_hosted_url}/health
                           │
                           ├─ 2xx → status = online
                           ├─ 5xx → status = degraded
                           └─ 超时/连接失败 → status = offline

• 用户启动时也会做一次即时健康检查（3 秒超时）
• offline 状态的插件无法启动，用户会看到 503 提示
• 管理员可通过后台手动触发检查

推荐部署方式

方式	适合
Docker + Nginx	通用、隔离性好
Vercel / Railway	Node.js 轻量服务
云函数 (Lambda / 云函数)	低频调用、按量计费
VPS 直接部署	完全控制

---

从托管迁移到自托管

1. 将代码部署到你的服务器
2. 确保 /health 端点可访问
3. 联系管理员更新 hosting_mode 为 self_hosted
4. 提供新的 self_hosted_url

从自托管迁移到托管

1. 打包代码为 .tar.gz（含 plugin.json）
2. 通过 API 提交新版本，hosting_mode 改为 managed
3. 审核通过后平台接管部署

---

故障排查

自托管插件显示 offline

1. 确认 /health 端点正常：curl -I https://your-url/health
2. 确认服务器对外网可访问（防火墙、安全组）
3. 确认 HTTPS 证书有效

托管插件启动失败

1. 检查 plugin.json 中 entry_point 路径是否正确
2. 确认依赖文件（requirements.txt / package.json）齐全
3. 查看平台日志中的错误信息

---

相关文档

• 第三方插件开发
• Process 插件开发
• 安全规范