OpenZiti/zrok项目Linux自托管部署指南

前言

OpenZiti/zrok是一个基于零信任网络架构的开源项目，它提供了一种安全、高效的方式来共享网络资源。本文将详细介绍如何在Linux系统上自托管部署zrok服务，帮助技术团队构建自己的零信任共享平台。

准备工作

在开始部署前，请确保您已具备以下条件：

1. 一台具有公网IP的Linux服务器
2. 配置好的通配符DNS记录（如*.zrok.example.com）
3. 服务器防火墙已开放必要的端口

OpenZiti基础架构部署

zrok依赖于OpenZiti（又称Ziti）提供安全的网络传输层。我们需要先部署Ziti控制器和路由器。

1. 部署Ziti控制器

1. 安装Ziti控制器软件包
2. 配置控制器启动文件（/opt/openziti/etc/controller/bootstrap.env）：
   • 设置服务器FQDN
   • 配置管理员密码
3. 开放防火墙对应端口
4. 启动控制器服务并验证状态

2. 部署Ziti路由器

1. 使用Ziti CLI创建路由器：

   ziti edge create edge-router "router1" -o /tmp/router1.jwt
   

2. 安装Ziti路由器软件包
3. 配置路由器启动文件（/opt/openziti/etc/router/bootstrap.env）：
   • 设置控制器和路由器地址
   • 使用上一步生成的JWT令牌
4. 开放防火墙对应端口
5. 启动路由器服务并验证状态

3. 验证网络状态

使用以下命令确认路由器已上线：

ziti edge list edge-routers

zrok安装与配置

1. 安装zrok软件包

Debian/Ubuntu系统：

sudo apt install zrok

其他Linux发行版可手动安装对应平台的二进制文件。

2. 控制器配置

创建控制器配置文件etc/ctrl.yml，包含以下关键部分：

v: 4
admin:
  secrets:
    - 随机生成的管理令牌
endpoint:
  host: 0.0.0.0
  port: 18080
store:
  path: zrok.db
  type: sqlite3
ziti:
  api_endpoint: "https://127.0.0.1:1280"
  username: admin
  password: "控制器密码"

重要说明：

• admin.secrets需使用随机生成的令牌
• ziti.password应与Ziti控制器密码一致
• 如需TLS，可配置cert_path和key_path

3. 环境变量设置

为使用自托管服务，需设置API端点：

export ZROK_API_ENDPOINT=http://127.0.0.1:18080

系统初始化

1. 引导OpenZiti网络

执行引导命令：

zrok admin bootstrap etc/ctrl.yml

此过程将：

• 初始化数据库
• 创建必要的Ziti身份
• 配置所有必需的Ziti策略

注意输出的警告信息，提示需要创建公共前端。

2. 启动zrok控制器

zrok controller etc/ctrl.yml

3. 创建公共前端

zrok admin create frontend <前端ID> public http://{token}.zrok.example.com:8080

前端ID可在引导日志或通过ziti edge list identities命令获取。

前端服务配置

1. 前端配置文件

创建etc/http-frontend.yml：

v: 3
host_match: zrok.example.com
address: 0.0.0.0:8080

2. 启动公共前端服务

zrok access public etc/http-frontend.yml

用户管理

1. 创建管理员账户

zrok admin create account <邮箱> <密码>

2. 邀请其他用户

zrok invite

被邀请用户可通过访问http://<控制器地址>/register/<令牌>完成注册。

3. 激活用户环境

用户需设置API端点并激活环境：

export ZROK_API_ENDPOINT=https://zrok.example.com
zrok enable <账户令牌>

验证部署

使用以下命令验证环境状态：

zrok status --secrets

高级配置建议

1. TLS配置：建议在前端使用反向代理（如Nginx、Caddy）处理TLS终止
2. 监控：可配置Prometheus和Grafana监控系统指标
3. 高可用：考虑部署多个前端实例实现负载均衡
4. 备份：定期备份zrok.db数据库文件

常见问题排查

1. 服务无法启动：检查端口是否被占用，防火墙设置是否正确
2. 前端无法连接：验证DNS解析和主机名匹配配置
3. 身份验证失败：确认Ziti控制器密码和zrok配置一致
4. 数据库问题：检查数据库文件权限和完整性

通过以上步骤，您已成功在Linux系统上部署了自托管的zrok服务。这套系统将为您的组织提供安全、可控的资源共享能力，同时保持零信任网络的安全特性。