Docker Compose 示例

本目录提供一组 docker compose 示例，用于在容器里启动 gmzta 并开启常见能力：

示例	Gvisor 配置文件	TUN 配置文件	适用场景
开启子网网关服务	01-gvisor-subnetnode.yaml	01-tun-subnetnode.yaml	把 Docker bridge 网络里的服务暴露到飞网
开启出口网关服务	02-gvisor-exitnode.yaml	02-tun-exitnode.yaml	让其它飞网设备通过该容器出网
开启WebDAV 文件共享服务	03-gvisor-webdav.yaml	03-tun-webdav.yaml	通过飞网访问容器挂载目录
使用入口网关服务	04-gvisor-in.yaml	04-tun-in.yaml	把本地或容器服务发布到互联网
开启高可用服务	05-gvisor-service.yaml	05-tun-service.yaml	把后端服务发布到飞网高可用服务
开启应用网关服务	06-gvisor-app.yaml	06-tun-app.yaml	通过飞网控制面板配置的应用规则代理指定域名
开启边路由服务	（暂不提供）	（暂不提供）	（暂不提供）

使用前准备

1. 安装 Docker 和 Docker Compose。
2. 在飞网控制面板创建授权密钥 GM_TOKEN。
3. 根据要使用的能力，在飞网控制面板完成设备能力授权、访问控制策略、服务高可用或应用网关配置。
4. 不建议把真实 GM_TOKEN 存储到 compose 文件内，避免密钥泄露。建议使用 环境变量或.env 文件。

.env 文件配置

在 docker-compose.yaml 同级目录新建 .env 文件：

GM_TOKEN=gmzta-authkey-xxxx
GM_HOSTNAME=docker-gmzta

.env 每行写一个 变量名=变量值，等号两边不要加空格。GM_TOKEN 请替换为飞网控制面板创建的授权密钥，GM_HOSTNAME 可按需修改为当前容器节点名称。

然后在 compose 中引用变量：

environment:
  - GM_TOKEN=${GM_TOKEN}
  - GM_HOSTNAME=${GM_HOSTNAME}

在 compose.yaml 所在目录执行启动命令时，Docker Compose 会自动读取 .env文件：

docker compose up -d

如果 .env 不在当前目录，可以手动指定：

docker compose --env-file ./prod.env up -d

推荐网络模式

TUN模式或Gvisor模式介绍
新手默认推荐用户空间网络（Gvisor），也就是：

environment:
  - GM_TUN=false

这个模式不需要挂载 /dev/net/tun，也不需要 NET_ADMIN 权限，适合对性能要求不高的容器场景：

如果需要更完整的TCP/IP三层协议转发能力、更高性能，或需要内核网络栈，可以启用 TUN 模式：

network_mode: host #注：使用 `network_mode: host` 后，不需要映射端口。
cap_add:
  - NET_ADMIN
  - NET_RAW
devices:
  - /dev/net/tun:/dev/net/tun
environment:
  - GM_TUN=true

最小启动模板

version: "3.7"

services:
  gmzta:
    image: registry.cn-beijing.aliyuncs.com/gmzta/gmzta:1.2.6-70ac9ac
    container_name: gmzta
    hostname: mini-gmzta
    environment:
      - GM_TOKEN=${GM_TOKEN}
      - GM_CONFIG_DIR=/var/lib/gmzta
      - GM_TUN=false
    volumes:
      - ./gmzta/state:/var/lib/gmzta
    restart: on-failure:3   # 最多重试3次

启动：

docker compose up -d

查看日志：

docker logs -f gmzta

进入容器：

docker exec -it gmzta sh

查看节点状态：

gmzta info

开启WebDAV 文件共享服务

docker compose yaml 文件示例： 开启WebDAV 文件共享服务。

environment:
  - GM_TOKEN=${GM_TOKEN}
  - GM_CONFIG_DIR=/var/lib/gmzta
  - GM_TUN=false
  - GM_WEBDAV=share docs /data/docs
volumes:
  - ./gmzta/state:/var/lib/gmzta
  - ./share:/data/docs

上述容器的功能等价于执行如下 gmzta 命令：

gmzta webdav share docs /data/docs

注意：

• /data/docs 必须是容器内存在的目录。
• 飞网控制面板的访问控制策略中，需要给该设备开启 “WebDAV 文件共享”功能的权限。
• 飞网控制面板的访问控制策略中，需要给访问WebDAV服务的端设备开启 “WebDAV 文件访问”功能的权限。

验证：

使用支持WebDAV协议的工具挂载访问上述共享，访问路径：http://100.100.100.100:8080/<网络名>/<飞网设备名>/<共享名>。

• Linux：sudo mount -t davfs http://100.100.100.100:8080 /mount/mywebdav (注：davfs 是可以解释webdav协议的文件系统)

• Windows：通过“映射网络驱动器”或“添加网络位置” 或使用命令“net use Z: http://100.100.100.100:8080”(可将Z替换为你需要的盘符)

使用入口网关服务

docker compose yaml 文件示例： 使用入口网关服务。

入口网关适合把容器内或同 compose 网络内的服务发布到互联网。

推荐使用自定义 bridge 网络，把后端服务和 gmzta 放在同一个网络里：

services:
  gmzta-gvisor-in:
    image: registry.cn-beijing.aliyuncs.com/gmzta/gmzta:1.2.6-70ac9ac
    container_name: gmzta-gvisor-in
    hostname: gmzta-gvisor-in
    environment:
      - GM_TOKEN=${GM_TOKEN}
      - GM_CONFIG_DIR=/var/lib/gmzta
      - GM_TUN=false
      - GM_IN=--https=443 http://nginx-gvisor-in:80
    volumes:
      - ./gmzta/state:/var/lib/gmzta
    networks:
      - gmzta-gvisor-in
    restart: unless-stopped

  nginx-gvisor-in:
    image: nginx
    container_name: nginx-gvisor-in
    hostname: nginx-gvisor-in
    networks:
      - gmzta-gvisor-in
    restart: unless-stopped

networks:
  gmzta-gvisor-in:
    name: gmzta-gvisor-in
    driver: bridge

上述容器的功能等价于执行如下 gmzta 命令：

gmzta in --bg --https=443 http://nginx-gvisor-in:80

注意：

• 飞网控制面板的DNS设置中，需要“开启域名证书”功能。
• 飞网控制面板的访问控制策略中, 给该设备授权“使用入口网关”功能。

验证：

• 在互联网中使用该入口网关域名，访问该入口网关服务。
• 本示例访问地址为：https://gmzta-gvisor-in.<tuandui>.gmzta.net，需根据实际飞网网络域名访问。

开启高可用服务

docker compose yaml 文件示例：开启高可用服务。

高可用服务适合把多个节点上的同类后端服务组成统一服务入口。

推荐配置：

services:
  gmzta-gvisor-service:
    image: registry.cn-beijing.aliyuncs.com/gmzta/gmzta:1.2.6-70ac9ac
    container_name: gmzta-gvisor-service
    hostname: gmzta-gvisor-service
    environment:
      - GM_TOKEN=${GM_TOKEN}
      - GM_CONFIG_DIR=/var/lib/gmzta
      - GM_TUN=false
      - GM_SERVICE=--ha=oa --https=6443 http://nginx-gvisor-service:80
    volumes:
      - ./gmzta/state:/var/lib/gmzta
    networks:
      - gmzta-gvisor-service
    restart: unless-stopped

  nginx-gvisor-service:
    image: nginx
    container_name: nginx-gvisor-service
    hostname: nginx-gvisor-service
    networks:
      - gmzta-gvisor-service
    restart: unless-stopped

networks:
  gmzta-gvisor-service:
    name: gmzta-gvisor-service
    driver: bridge

上述容器的功能等价于执行如下 gmzta 命令：

gmzta service --bg --ha=oa --https=6443 http://nginx-gvisor-service:80

注意：

• 需要在飞网控制面板“服务高可用”中新建服务，例如 oa，设置服务端口，例如 6443，容器启动与创建高可用服务不限制先后顺序。
• 需要在飞网控制面板批准该容器节点加入高可用服务，或者配置自动批准。
• 飞网控制面板的访问控制策略中，配置访问控制策略，允许用户访问该高可用服务。

验证：

• 使用飞网控制面板“服务清单”-“服务发布”中创建的该高可用服务域名，访问该高可用服务。
• 本示例访问地址为：https://oa.<tuandui>.gmzta.net，需根据实际高可用服务域名访问。

开启子网网关服务

docker compose yaml 文件示例： 开启子网网关服务。

注：只暴露一个后端子网设备时，使用 /32：

environment:
  - GM_SUBNETNODE=172.30.0.20/32

如果需要暴露示例文件中的整个 Docker 网络，可以写：

environment:
  - GM_SUBNETNODE=172.30.0.0/24

上述容器的功能等价于执行如下 gmzta 命令：

gmzta set --subnetnode 172.30.0.20/32

注意：

• 飞网控制面板需要批准该节点指定的子网范围，并配置访问控制策略。

验证：

• 登录飞网后，在不同网络环境下访问共享的容器服务地址，如：http://172.30.0.20 开启的nginx服务。

开启出口网关服务

docker compose yaml 文件示例：开启出口网关服务。

environment:
  - GM_OUTNODE=true

上述容器的功能等价于执行如下 gmzta 命令：

gmzta on --outnode=true

注意：

• 飞网控制面板需要批准出口网关。客户端使用出口节点时，还需要在客户端选择该出口节点。

验证：

使用 gmzta set out <出口网关设备飞网IP> 可为当前飞网节点指定出口网关。
设置完成后，可通过访问 https://www.ip138.com/ 等网站，确认当前节点的出口公网 IP。

开启应用网关服务

docker compose yaml 文件示例： 开启应用网关服务。

services:
  gmzta-gvisor-app:
    image: registry.cn-beijing.aliyuncs.com/gmzta/gmzta:1.2.6-70ac9ac
    container_name: gmzta-gvisor-app
    hostname: gmzta-gvisor-app
    dns:
      - 8.8.8.8
    dns_search:
      - testteam.gmzta.net
    environment:
      - GM_TOKEN=${GM_TOKEN}
      - GM_CONFIG_DIR=/var/lib/gmzta
      - GM_TUN=false
      - GM_GMZTA_EXTRA_ARGS=--appout=true
    volumes:
      - ./gmzta/state:/var/lib/gmzta
    restart: unless-stopped

注意：

• 需在飞网控制面板及时批准对应的应用网关。
• 使用此功能需确保当前设备为设备组设备，请使用带设备组的${GM_TOKEN}。
• 在飞网控制面板中新建应用网关,访问“飞网控制面板”-“应用网关”-添加网关-“网关名称”-“域名白名单”选择自动关联设备组。
• （可选）配置自动审批，当自动发现新的域名解析地址时可以自动许可，访问“飞网控制面板”-“访问控制”-增加自动审批。

上述容器的功能等价于执行如下 gmzta 命令：

gmzta on --appout=true

验证：

• 访问应用网关授权的白名单域名，根据实际配置内容测试。

排错：

应用网关依赖 DNS 解析。若日志出现：

dns: resolver: forward: no upstream resolvers set, returning SERVFAIL

通常表示容器没有可用的上游 DNS。请在 compose 中按实际网络环境显式配置可用的上游 DNS 服务器：

dns:
  - 8.8.8.8

看到类似日志说明应用规则已经下发：这表示该容器正在处理这类规则。最终是否走应用网关，需要从其它飞网客户端访问对应域名验证。

appc: handling domains: [] and wildcards: [qq.com]

常见排错

查看容器日志：

docker logs -f <容器名>

查看 gmzta 状态：

docker exec -it <容器名> gmzta info

查看服务配置：

docker exec -it <容器名> gmzta service info --json   
docker exec -it <容器名> gmzta in info
docker exec -it <容器名> gmzta webdav list

查看容器 DNS：

docker exec -it <容器名> cat /etc/resolv.conf

如果要使用固定 IP，请使用合法 IPv4 网段，例如：

networks:
  gmzta-gvisor-service:
    name: gmzta-gvisor-service
    driver: bridge
    ipam:
      config:
        - subnet: 172.31.0.0/24
          gateway: 172.31.0.1

常见问题：

• 目前 'GM_GMZTA_EXTRA_ARGS' 环境变量仅支持配置gmzta on 下子命令。
• no upstream resolvers set: 容器没有可用的上游 DNS，需要通过 compose 的 dns: 配置可用的上游 DNS 服务器。
• WebDAV 共享失败：确认目录存在、设备有 WebDAV 共享能力。
• 入口网关访问失败：确认飞网控制面板已开启域名证书和入口网关授权。
• 高可用服务不可访问：确认服务已创建、节点已在飞网控制面板批准、访问控制策略已放行。

推荐习惯

• 每个示例使用独立 GM_CONFIG_DIR 挂载目录，避免多个容器共用同一份状态。
• 正式环境不要固定写死 GM_TOKEN，使用 .env 或 Secret。
• 飞网容器代理其它容器服务时，优先使用同一个 bridge 网络和容器服务名访问后端。
• 需要内核转发或更高性能时，切换到 TUN 模式和 network_mode: host。