iii 引擎生产部署实战指南：Docker Compose 编排与反向代理配置

iii 引擎生产部署实战指南Docker Compose 编排与反向代理配置【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文面向需要把 iii 引擎engine及其 worker 部署到生产环境的开发者完整讲解iii project命令生成 Docker 资产、docker compose启动服务栈、以及 Caddy/Nginx 反向代理的三种传输面路由方案。读完本文你将掌握从零生成生产级部署文件、理解三个核心端口49134/3111/3112的职责划分并能为引擎正确配置 TLS 终止与 WebSocket 升级代理。本指南以 docs/using-iii/deployment.mdx 为主体骨架并结合仓库内engine源码、模板与端到端测试进行深度印证。本地开发环境的启动方式可参考 Quickstart 与 Engine 页面CLI 的完整命令面见 CLI 参考。iii Cloud 托管部署即将推出iii cloud子命令组将负责管理托管形式的 iii 部署。由于该命令面仍在演进中具体命令形态如 deploy、logs、ssh、env 等会在稳定后随 CLI 文档 一同补齐。官方文档中注明iii cloud 即将可用available soon在阅读本文时请始终以最新文档与iii cloud --help的实际输出为准。对于当下需要上线服务的团队仓库提供的 Docker 部署路径是唯一正式支持的自托管方式下面展开。使用 Docker 部署一行命令生成完整部署资产两种入口新建项目与存量项目iii 的 CLI 为 Docker 部署提供了两种等价入口均位于iii project命令组实现见 engine/src/cli/project/mod.rs新建项目iii project init --docker在初始化项目的同时一并生成 Docker 资产CLI 定义中明确注释 Also generate Docker assets (Dockerfile, docker-compose.yml, .env). Equivalent to runningiii project generate-dockerseparately存量项目iii project generate-docker为已存在的项目补充 Docker 资产iii project generate-docker执行成功后CLI 会在项目根目录打印✓ Docker assets generated at path并提示下一步docker compose up。相关参数还包括--directory path指定目标目录、--template-dir path本地模板目录便于离线或自定义模板场景模板来源可通过III_TEMPLATE_URL环境变量调整。生成的三份文件两种形式都会在项目根目录生成三个文件文件作用Dockerfile基于iiidev/iii:latest构建镜像distroless、非 root 运行docker-compose.yml服务编排端口映射、数据卷、.env注入、重启策略.env环境变量文件内含随机生成的 RabbitMQ 凭据勿提交到版本库重要行为重复运行生成器不会覆盖已有文件。这由源码中的write_if_absent与write_env_if_absent实现engine/src/cli/project/mod.rs——只有当目标文件不存在时才写入。因此你对模板做的任何自定义修改都会在后续重新生成时保留可以放心编辑。从源码实现还可以看到两个值得注意的细节device_id 烘焙Dockerfile 模板中带有字面量占位符__III_DEVICE_ID__生成时会被替换为项目实际的设备 IDsubstitute_device_id见 engine/src/cli/project/mod.rs从而运行时不再依赖III_HOST_USER_ID环境变量。.env自动生成凭据生成器会创建一个随机 UUID 作为RABBITMQ_PASS同时写入RABBITMQ_USERiii供注释掉的 RabbitMQ 服务和引擎展开${VAR}占位符时使用。文件头明确标注 Do not commit。端到端测试 engine/tests/project_init_e2e.rs 对上述行为做了完整验证--docker初始化会写出三份资产并替换 device_id 占位符第 169-204 行、generate-docker会复用已存在的 project.ini 中的 device_id第 215-240 行、未初始化项目时命令仍成功但会给出警告第 353 行起。启动服务栈docker compose up -d生成的docker-compose.yml将引擎容器的三个端口映射到宿主机端口服务49134SDK WebSocketworker 连接3111REST API3112Stream API完整的生成模板见 engine/tests/fixtures/templates/docker/docker-compose.yml引擎服务挂载./config.yaml:/app/config.yaml:ro只读配置、声明iii_data命名卷持久化运行时数据worker 注册等引擎状态iii.lock 由引擎首次运行自动创建不需要从宿主机 COPY、通过env_file: .env注入环境变量并设置了restart: unless-stopped与RUST_LOGinfo。compose 文件中还带有注释掉的 Redis 和 RabbitMQ 服务当 worker 需要外部适配器例如 Stream worker 依赖 Redis 作为 pub/sub 后端时取消注释即可。仓库根目录的 engine/docker-compose.yml 展示了一份完整的启用形态包含带健康检查的redis:7-alpine与rabbitmq:3-management-alpine服务且引擎通过depends_on的condition: service_healthy等待依赖就绪。生成的 Dockerfile 与镜像基础生成的 Dockerfile模板见 engine/tests/fixtures/templates/docker/Dockerfile核心内容如下FROM iiidev/iii:latest ENV III_EXECUTION_CONTEXTdocker ENV III_HOST_USER_IDdevice_id WORKDIR /app COPY config.yaml /app/config.yaml EXPOSE 49134 3111 3112 ENTRYPOINT [/app/iii] CMD [--config, /app/config.yaml]仓库自带的 engine/Dockerfile 揭示了基础镜像的内部形态基于gcr.io/distroless/cc-debian12:nonrootdistroless、非 root 用户UID 65532预创建/app/data、/app/config、/data目录并设置属主WORKDIR锚定到/app使相对路径默认值./config配置存储、./data数据目录落在可挂载卷的目录中入口为/app/iii。这些细节意味着生产环境需要注意镜像内无 shell调试需依赖日志RUST_LOG与健康检查数据与配置必须通过卷挂载持久化否则容器重建会丢失运行时状态III_EXECUTION_CONTEXTdocker由镜像与生成模板双重设置用于引擎感知自身运行环境。配置引擎服务端口引擎的监听端口并非写死在二进制中。以 Stream API 为例engine/config.yaml 中通过环境变量占位符配置workers: - name: iii-stream config: port: ${STREAM_PORT:3112} host: 127.0.0.1 adapter: name: redis config: redis_url: redis://localhost:6379${STREAM_PORT:3112}表示默认 3112、可用环境变量覆盖这意味着你在调整 compose 端口映射的同时也要保证引擎内部实际监听端口一致。配置反向代理TLS 终止与三传输面路由引擎自身不终止 TLS。生产环境必须在引擎前面放置反向代理负责 TLS 证书管理并将三个传输面路由到正确的端口/api/*→ REST API3111/stream/*→ Stream API3112/ws→ SDK WebSocket49134Caddy 配置示例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 会自动为your-domain.com申请和续期证书handle块按前缀精确分流。仓库自身的生产编排 engine/docker-compose.prod.yml 与 engine/Caddyfile 展示了同一套思路在容器网络中的形态caddy:2-alpine在前reverse_proxy iii:3111等服务名直连引擎容器。注意仓库自带的 Caddyfile 使用了/streams/*前缀与本文档示例的/stream/*略有差异接入时请以你自己的路由约定为准。以上仅是示例配置完整配置如 SSL 证书管理、请求头、超时等选项请查阅 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头否则 SDK 的 WebSocket 长连接与 Stream 流式连接会握手失败兜底路由location /把其余所有请求包括控制台等静态面转发到 3111 的 REST API。示例仅覆盖了路由骨架生产环境的 SSL 证书、安全响应头、请求体大小限制、代理超时等选项请参考 Nginx 官方文档。部署检查清单结合文档与仓库实现生产上线前建议逐项确认运行iii project generate-docker或iii project init --docker生成三份资产确认.env已生成且不会提交到版本库docker compose up -d后验证三个端口49134worker 通过 SDK WebSocket 连接、3111REST API、3112Stream API均可访问确认引擎工作目录相对路径./config、./data落在持久化卷上容器重建后配置与运行时状态不丢失在引擎前配置反向代理/ws与/stream/务必带上 WebSocket 升级头若 worker 依赖 Redis/RabbitMQ 适配器取消 compose 中对应服务注释并正确配置.env凭据使用RUST_LOG与健康检查参考 engine/docker-compose.prod.yml 中nc -z 127.0.0.1 3111的探针写法建立可观测性。小结iii 引擎的生产部署路径清晰而克制CLI 一键生成基于 distroless 非 root 镜像的 Docker 资产compose 负责端口、卷与依赖编排反向代理承担 TLS 终止与三传输面路由。理解 49134/3111/3112 三个端口的职责、生成文件不覆盖的语义、以及 WebSocket 升级代理的必要性是这套方案在生产环境稳定运行的关键。相关实现可进一步阅读 engine/src/cli/project/mod.rs、engine/Dockerfile 与 engine/tests/project_init_e2e.rs。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考