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 项目官方文档《Deployment》展开完整覆盖 iii 引擎从 Docker 容器化部署到反向代理接入的生产环境方案包括如何用iii project generate-docker一键生成 Dockerfile、docker-compose.yml 与 .env 三件套、各传输端口REST / Stream / WebSocket / Prometheus的规划以及 Caddy 与 Nginx 两种反向代理的完整配置。结合仓库内 Docker 生成器源码 与 官方镜像 Dockerfile文章进一步解析了模板占位符替换、设备 ID 注入与凭据生成等底层机制帮助你在生产环境可靠地运行 iii 引擎及其 workers。生产部署概览iii 的部署模型可以概括为引擎engine本身不提供 TLS 终结能力它以容器或裸进程形式暴露多个 HTTP/WebSocket 传输面由前置反向代理统一处理 TLS 与路由。文档将运行环境划分为两类本地开发参考 Quickstart 与 Engine 文档生产环境本文主题Docker Compose 编排 反向代理或直接使用 iii Cloud 托管服务。iii Cloud托管部署入口iii cloud子命令组用于管理托管的 iii 部署deploy、logs、env 等操作面在稳定后会在 CLI 文档 中逐一枚举。当前文档标注 iii Cloud 即将上线因此这一节更多是了解命令面的占位。从源码结构看cloud命令在引擎 CLI 中已注册为一个passthrough 桩stub其职责是把调用转发给独立维护的外部二进制gen_docs.rs 中声明console与cloud子命令为 passthrough stubregistry.rs 将cloud映射到外部iii-cloud二进制仓库iii-hq/iii-cloud-cli并有对应测试test_resolve_cloud验证该解析逻辑。也就是说即使未来 iii Cloud 完全落地iii cloud的行为也取决于外部 CLI 工具引擎仓库本身只负责命令分发。在确认 iii Cloud 可用性前生产部署应以下面的 Docker 方案为主。Docker 部署CLI 生成 Compose 编排生成 Docker 资产iii 用 CLI 直接生成项目根目录下的 Docker 资产有两种入口新项目iii project init --docker在初始化时顺带生成 Docker 资产等价于之后单独执行一次generate-docker已有项目iii project generate-docker。iii project generate-docker两种形式都会在项目根目录输出三个文件Dockerfile、docker-compose.yml和.env。重复执行不会覆盖已有文件因此你对模板的修改可以长期保留。这一点在源码中可以直接验证project/mod.rs 的apply_docker函数约 L353-L369对两个模板文件统一调用write_if_absentL383-L388其语义是路径已存在则直接跳过fn write_if_absent(path: Path, contents: [u8]) - std::io::Result() { if path.exists() { return Ok(()); } std::fs::write(path, contents) }当目标目录已有旧文件时CLI 的错误提示也印证了这一设计remove existing Dockerfile/docker-compose.yml or check write permissions。启动服务栈docker compose up -d生成的docker-compose.yml对外暴露以下端口端口服务49134SDK WebSocketworker 连接3111REST API3112Stream API9464Prometheus 指标其中 49134 是 SDK 与引擎握手的主通道worker 通过该 WebSocket 注册并接收函数调用3111/3112 是面向 HTTP 客户端与流式订阅的 REST/Stream 接口Prometheus 指标端口 9464 由可观测性组件提供据 SDK 参考文档该端点由iii-observabilityworker 提供通常与引擎同容器暴露。生成的 Dockerfile构建于 distroless 非根镜像之上生成的 Dockerfile 基于iiidev/iii:latest官方镜像构建。仓库根部的 engine/Dockerfile 就是该官方镜像的构建定义可以看到它基于gcr.io/distroless/cc-debian12:nonroot即以distroless 非 root 用户UID 65532运行并预创建/app/data、/app/config、/data三个数据目录供卷挂载持久化EXPOSE 49134 3111 3112与上表一致。以 Docker 模板文件 为例这也是生成器实际分发的内容与 project_init_e2e 测试 一起被端到端校验# iii project Dockerfile — generated by iii project generate-docker. # Edit freely; re-running the generator will not overwrite this file. FROM iiidev/iii:latest ENV III_EXECUTION_CONTEXTdocker ENV III_HOST_USER_ID__III_DEVICE_ID__ WORKDIR /app COPY config.yaml /app/config.yaml # iii.lock is engine-managed runtime state (worker registration); the engine # creates it on first run if missing, so we dont COPY it from the host. EXPOSE 49134 3111 3112 ENTRYPOINT [/app/iii] CMD [--config, /app/config.yaml]几个值得注意的实现细节__III_DEVICE_ID__占位符替换。模板中的III_HOST_USER_ID并不直接写死。生成器在apply_docker中调用substitute_device_idproject/mod.rs L371-L381将占位符替换为本机的实际 device_id如果模板中缺失该占位符生成器会直接报错the template repo and engine are out of sync。这样镜像运行时不再需要额外注入III_HOST_USER_ID环境变量。不复制iii.lock。iii.lock是引擎自管的运行时状态worker 注册表引擎首次启动时会自行创建因此镜像构建阶段刻意不 COPY 它——既避免污染镜像也保证全新项目能顺利通过docker build。III_EXECUTION_CONTEXTdocker告知引擎当前运行于容器环境引擎据此调整自身行为如文件系统/设备相关的处理路径。生成的 docker-compose.yml挂载、环境变量与外部适配器Compose 模板见 模板文件的核心内容services: iii: build: context: . ports: - 49134:49134 # WebSocket (worker connections) - 3111:3111 # REST API - 3112:3112 # Stream API volumes: - ./config.yaml:/app/config.yaml:ro - iii_data:/app/data env_file: .env environment: - RUST_LOGinfo - III_EXECUTION_CONTEXTdocker restart: unless-stopped # Uncomment if your workers need Redis. # redis: # image: redis:7-alpine # ports: # - 6379:6379 # volumes: # - redis_data:/data # restart: unless-stopped # Uncomment if your workers need RabbitMQ. # rabbitmq: # image: rabbitmq:3-management-alpine # ports: # - 5672:5672 # - 15672:15672 # environment: # - RABBITMQ_DEFAULT_USER${RABBITMQ_USER} # - RABBITMQ_DEFAULT_PASS${RABBITMQ_PASS} # volumes: # - rabbitmq_data:/var/lib/rabbitmq # restart: unless-stopped volumes: iii_data: # redis_data: # rabbitmq_data:配置以只读卷挂载./config.yaml:/app/config.yaml:ro容器内不可改配置变更必须走宿主文件运行时数据持久化命名卷iii_data挂载到/app/data跨容器重建保留引擎运行状态restart: unless-stopped保证异常退出后自动拉起外部适配器按需启用compose 文件内置了被注释的 Redis 与 RabbitMQ 服务当 worker 需要外部 KV / 消息队列适配时取消对应注释即可让 broker 与引擎同网络启动。.env 文件自动生成的 RabbitMQ 凭据.env不是普通占位文件。生成器中的write_env_if_absentproject/mod.rs L390-L402会在文件不存在时写入# Generated by iii project generate-docker. Do not commit. RABBITMQ_USERiii RABBITMQ_PASS随机生成的 UUID即密码是一个随机 UUID用户名固定为iii。其用途有两处引擎在展开配置中的${VAR}占位符时会读取这些变量上面被注释的 RabbitMQ 服务则用${RABBITMQ_USER}/${RABBITMQ_PASS}初始化 broker 默认账号。文件头明确标注Do not commit应通过.gitignore排除出版本库。配置反向代理TLS 终结与三传输面路由引擎本身不终结 TLS。生产部署需要在其前面放置反向代理由代理处理证书并把三个传输面路由到对应端口路径前缀目标端口说明/api/*3111REST API/stream/*3112Stream API/ws49134SDK WebSocketCaddy 配置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 指令如自动 HTTPS、日志、限流等应参考官方 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; } }同样这只是最小可用示例SSL 证书、请求头透传、超时等完整选项应参考官方 Nginx 文档。与 Compose 服务名配合使用值得对比的是仓库内自带的 engine/Caddyfile 是一份面向 Compose 网络环境的示例它不代理到127.0.0.1而是直接以容器服务名iii为目标reverse_proxy iii:3111等适用于反向代理与引擎容器同网络部署的场景。另外可以观察到该示例文件使用了/streams/*前缀而本文档使用的是/stream/*——从两份文件并存的结构看路由前缀在不同文档/示例间存在差异落地时以你自己反代实际配置的 location/handle 前缀与引擎行为对齐为准。小结与延伸阅读命令面iii project init --docker与iii project generate-docker生成三件套且不覆盖已有文件docker compose up -d启动引擎栈iii cloud为托管部署预留的 passthrough 命令。端口面49134SDK WebSocket、3111REST、3112Stream、9464Prometheus 指标。安全面TLS 一律由前置反向代理终结.env内含自动生成的 RabbitMQ 凭据切勿提交到版本库。相关仓库文件Docker 生成器实现、官方镜像 Dockerfile、docker-compose 模板、Dockerfile 模板、project init 端到端测试相关文档Quickstart、Engine、CLI。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考