OpenZiti 入门（17）：使用 Docker Compose 部署 OpenZiti

从本篇开始，我们进入 Docker 部署与避坑系列。第一篇先用官方 Docker Compose Quickstart，在单机启动 Controller、Router 和 Ziti Admin Console（ZAC）。

本文以安装了 Docker Engine 和 Compose 插件的 Ubuntu 为例。Quickstart 适合学习和短期实验；它会创建一套新网络，前面文章中的身份和服务不会自动出现在这套网络中。官方 Docker Compose Quickstart也将该方案定位为学习环境。

1. 检查 Docker 和 Compose。

   bash
   docker version
   docker compose version
   

   如果 Docker 尚未安装，可参考 Docker 官方 Ubuntu 安装指南。执行 Docker 命令时还需要当前用户有访问 Docker daemon 的权限。

2. 下载 OpenZiti Compose 文件。

   bash
   mkdir -p ~/openziti-docker-lab
   cd ~/openziti-docker-lab
   
   curl -fsSL https://get.openziti.io/dock/docker-compose.yml \
     -o compose.yaml
   
   curl -fsSL https://get.openziti.io/dock/.env \
     -o .env
   
   chmod 600 .env
   

   官方配置会启动 Controller、多个 Router、ZAC 和一个演示 Web 容器。Compose 文件和 .env 应保存在同一目录。

3. 设置本地监听地址和管理员密码。

   编辑 .env：

   bash
   nano .env
   

   找到并修改以下变量：

   dotenv
   ZITI_INTERFACE=127.0.0.1
   ZITI_USER=admin
   ZITI_PWD=请替换为自己的强密码
   

   本例将发布端口绑定到 127.0.0.1，方便在 Docker 主机本地实验。请在首次启动之前设置密码；如果密码包含 $ 等特殊字符，需要遵循 Compose .env 语法。

   当前官方示例可能使用到 80、1280、3022、3023 和 8443 等端口。启动前可以用下面的命令检查占用情况：

   bash
   sudo ss -lntp
   

   如果 80 已被其他网站占用，可在 compose.yaml 的 web-test-blue 部分，将宿主机映射从 80:8000 改为 8080:8000；容器内端口仍为 8000。

4. 启动并检查容器。

   在配置文件所在目录执行：

   bash
   docker compose config --quiet
   docker compose up -d
   docker compose ps -a
   

   首次启动需要拉取镜像和初始化网络。Controller 应最终显示运行且健康；初始化容器执行完成后以退出码 0 结束属于正常情况。

   如果 Controller 或 Router 没有正常启动，先查看日志：

   bash
   docker compose logs --tail=100 ziti-controller
   docker compose logs --tail=100 ziti-edge-router
   

5. 验证 Controller 和 Router。

   进入 Controller 容器：

   bash
   docker compose exec ziti-controller bash
   

   在容器内登录并查看 Router：

   bash
   zitiLogin
   ziti edge list edge-routers
   

   等待初始化完成后，应能看到 Router，且相关 Router 的在线状态为 true。输入 exit 返回宿主机。zitiLogin 的输出可能包含会话信息，发布排障日志前应检查其中的敏感内容。

6. 访问 Ziti Admin Console。

   默认 Compose 配置使用 ziti-edge-controller 作为 Controller 名称。在运行浏览器的本机 /etc/hosts 中加入：

   text
   127.0.0.1 ziti-edge-controller ziti-edge-router ziti-edge-router-wss
   

   然后访问：

   text
   https://ziti-edge-controller:8443
   

   首次配置 Controller URL 时，填写：

   text
   https://ziti-edge-controller:1280
   

   使用 .env 中设置的管理员账号和密码登录。Quickstart 使用实验用证书，浏览器可能提示证书未受信；请确认访问的是自己的实验环境，并按 ZAC 官方指南处理证书。

   如果 Docker 运行在远程 Ubuntu 服务器上，127.0.0.1 绑定的端口不能直接从外部访问。可以先通过 SSH 转发 ZAC 和 Controller API 端口，再在浏览器所在电脑配置上述主机名。

几个常见坑：

• 端口被占用：检查 docker compose ps -a 和容器日志。尤其注意演示 Web 使用的 80 端口，以及已有 ZAC 可能占用的 8443。
• 容器在线，但外部设备连接不上：容器名只在对应 Docker 网络内自动解析。外部客户端还需要可解析、可到达且与证书匹配的 Controller 和 Router 地址；开放端口本身不足以完成配置。
• 修改 .env 后密码或地址没有按预期变化：Controller 数据库和 PKI 保存在 Docker 卷中，已有网络不会因为修改环境变量就自动重新初始化。
• 不要误删数据卷：docker compose down 默认保留卷；使用 down -v 会删除卷，连同其中的数据库和 PKI。保持 Compose 项目名一致，也有助于重新使用原来的卷。
• 镜像版本变化：官方示例默认使用 latest。需要可重复部署时，应保存本次 Compose 文件，并固定经过验证的镜像版本。