企业官网建设流程全解析

iii 引擎生产部署指南：Docker Compose 生成与 Caddy/Nginx 反向代理配置

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

本篇指南讲解如何将 iii 引擎及其 worker 部署到生产环境：通过 CLI 一键生成Dockerfile、docker-compose.yml与.env资产，再用 Compose 拉起整个服务栈；随后在前端放置反向代理，处理 TLS 并正确路由 REST、Stream 与 WebSocket 三个传输面。读完本文，你将掌握 iii 的标准容器化部署流程、端口规划、代理路由规则及其背后的 CLI 实现原理。本文对应仓库文档为 deployment.mdx，本地开发可参考 Quickstart 与 Engine。

部署模型总览

iii 引擎在生产环境采用「单引擎进程 + 多传输面」的拓扑：一个引擎进程同时暴露 REST API、Stream API 与 SDK WebSocket 三个服务面，worker 通过 WebSocket 与引擎保持长连接。反向代理位于引擎之前，负责 TLS 终止与按路径分流。容器化是官方推荐的生产交付方式，CLI 将生成资产的细节封装为模板，开发者只需执行两条命令即可获得一套可运行的 Compose 栈。

从源码结构看，这套设计将「模板内容」与「引擎发布」解耦：iii project子命令的模板（含 Docker 资产）全部存放在独立的模板仓库，运行时通过scaffolder_core::TemplateFetcher拉取，引擎二进制本身不内嵌模板内容（见 engine/src/cli/project/mod.rs 的模块注释）。

使用 Docker 部署

生成 Docker 资产：两种等价方式

CLI 提供两条路径生成 Docker 资产，产物完全一致：

• 新项目一步到位：iii project init --docker
• 已有项目补充生成：iii project generate-docker

iii project generate-docker

两者的等价关系在源码中有明确注释：「Also generate Docker assets (Dockerfile, docker-compose.yml, .env). Equivalent to runningiii project generate-dockerseparately.」（见 engine/src/cli/project/mod.rs）。也就是说init --docker在初始化项目骨架之后，内部复用了与generate-docker相同的apply_docker逻辑。

generate-docker支持两个可选参数（见 CLI 参考）：

其中--template-dir对应源码中的build_fetcher分支，便于离线调试模板内容。

生成的三个文件

两种命令都会在项目根目录产出三个文件：

关键特性：生成过程是幂等的。重新运行生成器不会覆盖已存在的文件，因此你对模板的手工修改可以保留。这在源码中由write_if_absent实现——只有目标文件不存在时才写入（见 engine/src/cli/project/mod.rs）。若文件已存在且生成失败，CLI 会提示「remove existing Dockerfile/docker-compose.yml or check write permissions」（engine/src/cli/project/mod.rs）。

端口规划

生成的docker-compose.yml暴露以下端口：

仓库根目录下的参考编排文件 engine/docker-compose.yml 展示了相同的端口映射（49134WebSocket、3111REST、3112Stream），并额外显式映射了9464供 Prometheus 指标抓取，同时通过volumes将宿主机config.yaml只读挂载进容器、以III_EXECUTION_CONTEXT=docker标注运行上下文，可作为自行编排时的对照参考。另外，worker 配置中port字段与这些端口直接对应——例如引擎内置的 Stream worker 即配置为port: 3112（见 engine/src/workers/config.rs 的配置解析测试）。

启动服务栈

docker compose up -d

Dockerfile 基于iiidev/iii:latest（distroless、非 root 用户运行），降低容器内提权风险。生成的 compose 文件中附带被注释掉的 Redis 与 RabbitMQ 服务——当 worker 需要外部适配器（如队列、KV 存储）时，取消注释即可启用。仓库参考编排文件同样内置了redis:7-alpine与rabbitmq:3-management-alpine两个服务，并配置了健康检查与restart: unless-stopped策略（engine/docker-compose.yml）。

生成原理：模板拉取与占位符替换

generate-docker的底层实现（apply_docker，见 engine/src/cli/project/mod.rs）值得了解：

1. 通过TemplateFetcher从模板仓库拉取docker模板下的Dockerfile与docker-compose.yml两个文件；
2. 刻意跳过shared_files合并逻辑，避免重新拷贝config.yaml/.gitignore覆盖用户已有定制（源码注释明确说明这一设计取舍）；
3. Dockerfile 模板内含字面量占位符__III_DEVICE_ID__，生成时替换为实际的device_id再落盘，使镜像运行时不再依赖III_HOST_USER_ID环境变量；
4. 生成的.env携带 RabbitMQ 凭据，引擎在展开${VAR}占位符时读取，注释掉的 RabbitMQ 服务同样使用这份凭据。

iii Cloud 托管部署

iii cloud子命令组将用于管理托管的 iii 部署，相关命令面（deploy、logs、ssh、env 等）正在随 CLI 一起稳定中。原文档明确标注：iii 的云端服务即将推出（iii's cloud will be available soon.），当前生产环境请优先采用上文的自托管 Docker 方案。

配置反向代理

iii 引擎自身不终止 TLS。生产环境必须在引擎之前放置反向代理，由代理处理 TLS 证书并按下述规则路由三个传输面：

Caddy 配置示例

your-domain.com { handle /api/* { reverse_proxy 127.0.0.1:3111 } handle /stream/* { reverse_proxy 127.0.0.1:3112 } handle /ws { reverse_proxy 127.0.0.1:49134 } handle { reverse_proxy 127.0.0.1:3111 } }

Caddy 对/ws与/stream/*的 WebSocket 升级是自动处理的，无需显式声明 Upgrade 头。上例仅为最小路由骨架，完整的 TLS、日志与安全配置请参考 Caddy 官方文档。

Nginx 配置示例

server { listen 443 ssl; server_name your-domain.com; location /api/ { proxy_pass http://127.0.0.1:3111; } location /ws { proxy_pass http://127.0.0.1:49134; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location /stream/ { proxy_pass http://127.0.0.1:3112; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } location / { proxy_pass http://127.0.0.1:3111; } }

Nginx 下必须显式处理 WebSocket 升级：对/ws与/stream/两个 location 设置proxy_http_version 1.1，并传递Upgrade与Connection "upgrade"头，否则 worker 长连接无法建立。ssl证书配置、请求头增强与代理超时等完整参数请参考 Nginx 官方文档。

部署后的验证清单

从引擎的配置解析与 CLI 实现可以推断出以下自检要点，供上线时逐项核对：

1. 端口可达性：确认 49134 / 3111 / 3112 在容器网络内可访问，且未被宿主防火墙拦截；
2. WebSocket 升级：通过代理建立 SDK 连接时，确认代理正确透传 Upgrade 头（Nginx 场景最易遗漏）；
3. worker 注册：worker 通过/ws连接到引擎后，使用iiiCLI 或 Console 确认 worker 已注册上线；
4. 外部适配器：若 worker 依赖队列或 KV 适配器，取消注释 Redis/RabbitMQ 服务并确认.env凭据与引擎${VAR}展开一致；
5. 配置挂载：容器内config.yaml的变更需重启引擎生效，注意参考编排中的只读挂载方式。

相关阅读

• iii 引擎架构：理解 REST / Stream / WebSocket 三个传输面的职责划分
• CLI 参考：iii project全部子命令与选项的完整说明
• 使用 Console：部署后通过可视化界面观察 worker 与事件流
• 参考编排文件：仓库内置的完整 Compose 样例（含指标端口与健康检查）

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii