|
| 1 | +# Docker 部署 |
| 2 | + |
| 3 | +本页面介绍如何使用官方镜像运行 `tuic-server`。客户端仍按[快速入门](getting-started.md)在宿主机或其它容器中运行。 |
| 4 | + |
| 5 | +## 前置条件 |
| 6 | + |
| 7 | +- 已安装 Docker;使用 Compose 时需要 Docker Compose 插件。 |
| 8 | +- 服务器必须允许 **UDP** 监听端口(默认示例为 `8443`)。 |
| 9 | +- 一个用于存放 `config.toml` 的宿主机目录,例如 `/etc/tuic`。 |
| 10 | + |
| 11 | +## 镜像 |
| 12 | + |
| 13 | +镜像由 CI 从 `.github/Dockerfile` 构建并发布到 GitHub Container Registry: |
| 14 | + |
| 15 | +```console |
| 16 | +docker pull ghcr.io/itsusinn/tuic-server:latest |
| 17 | +``` |
| 18 | + |
| 19 | +- 同时提供 `linux/amd64` 与 `linux/arm64` 两种架构。 |
| 20 | +- `latest` 指向最近一次发布;也可以使用对应的版本标签(例如 `ghcr.io/itsusinn/tuic-server:1.2.3`)。 |
| 21 | +- 镜像入口为 `tuic-server`,默认命令为 `-d /etc/tuic`,因此会读取挂载到 `/etc/tuic` 的配置目录。 |
| 22 | +- 容器内设置了 `IN_DOCKER=true`。 |
| 23 | + |
| 24 | +## 准备配置 |
| 25 | + |
| 26 | +容器不包含配置文件,需要先在宿主机上生成。可以借助一次性容器调用 `--init`: |
| 27 | + |
| 28 | +```console |
| 29 | +mkdir -p /etc/tuic |
| 30 | +docker run --rm -v /etc/tuic:/etc/tuic ghcr.io/itsusinn/tuic-server --init |
| 31 | +``` |
| 32 | + |
| 33 | +该命令会在 `/etc/tuic` 中生成一个包含 5 个随机用户的 `config.toml`;若文件已存在则不会覆盖。你也可以从[快速入门](getting-started.md)中的最小配置开始,或使用[配置生成器](/config-generator/)在浏览器本地生成成对的服务器与客户端配置。 |
| 34 | + |
| 35 | +请确认 `config.toml` 中的 `server` 监听地址允许来自容器的连接,例如 `[::]:8443`。 |
| 36 | + |
| 37 | +## 运行容器 |
| 38 | + |
| 39 | +### docker run |
| 40 | + |
| 41 | +```console |
| 42 | +docker run -d \ |
| 43 | + --name tuic-server \ |
| 44 | + --restart unless-stopped \ |
| 45 | + -p 8443:8443/udp \ |
| 46 | + -v /etc/tuic:/etc/tuic:ro \ |
| 47 | + ghcr.io/itsusinn/tuic-server:latest |
| 48 | +``` |
| 49 | + |
| 50 | +- `-p 8443:8443/udp` 必须显式指定 `/udp`;TUIC 不使用 TCP 监听端口。 |
| 51 | +- `-v /etc/tuic:/etc/tuic:ro` 以只读方式挂载配置目录,与默认命令 `-d /etc/tuic` 对应。 |
| 52 | +- 如需使用不同的目录,请覆盖命令,例如 `ghcr.io/itsusinn/tuic-server -d /config`。 |
| 53 | + |
| 54 | +### Docker Compose |
| 55 | + |
| 56 | +```yaml |
| 57 | +services: |
| 58 | + tuic-server: |
| 59 | + image: ghcr.io/itsusinn/tuic-server:latest |
| 60 | + container_name: tuic-server |
| 61 | + restart: unless-stopped |
| 62 | + ports: |
| 63 | + - "8443:8443/udp" |
| 64 | + volumes: |
| 65 | + - /etc/tuic:/etc/tuic:ro |
| 66 | +``` |
| 67 | +
|
| 68 | +若服务器使用 ACME 自动申请证书,HTTP-01 验证还需要开放 **TCP 端口 80**。此时可在 `ports` 中追加 `"80:80/tcp"`,或改用 `network_mode: host` 让容器直接使用宿主机网络。 |
| 69 | + |
| 70 | +## 验证 |
| 71 | + |
| 72 | +```console |
| 73 | +docker logs tuic-server |
| 74 | +``` |
| 75 | + |
| 76 | +日志应显示服务器正在监听并已准备好进行 TLS 连接。随后从本地机器向服务器发送一个 SOCKS5 请求进行验证。 |
| 77 | + |
| 78 | +## 排错 |
| 79 | + |
| 80 | +- **客户端无法连接**:确认 UDP 端口已放行、端口映射包含 `/udp`,以及云服务商的安全组允许 UDP。 |
| 81 | +- **TLS 验证失败**:确认客户端 `tls.sni` 与证书域名一致;自签名证书仅在测试时使用 `skip_cert_verify = true`。 |
| 82 | +- **ACME 申请失败**:确认 `80/tcp` 可达,且域名已正确解析到服务器。 |
| 83 | + |
| 84 | +通过配置验证仅表示字段有效;并不意味着 DNS、证书、防火墙或实际网络连接已通过验证。 |
0 commit comments