平台架构概览 - 回归终端

本页介绍回归终端的运维架构，重点说明平台服务与外部组件之间的关系。部署前可以先通过本页确认必需服务、可选服务、外置方案和关闭某些组件后的功能变化。具体安装命令见后续部署指南。

核心边界

回归终端的运行时核心是 ret2shell 平台服务。平台服务对外提供 Web 页面、HTTP API、WebSocket、镜像仓库代理和题目实例控制接口，对内连接数据库、缓存、消息队列、文件存储、日志系统和 Kubernetes 集群。

Browser / Player / Admin
        |
        v
Gateway / Ingress / Nginx / Caddy
        |
        +--> static frontend
        |
        v
ret2shell platform service
        |
        +--> PostgreSQL          persistent platform data
        +--> Valkey / Redis      sessions, tokens, cache, rate limit
        +--> NATS JetStream      asynchronous jobs and event fanout
        +--> local / PVC files   game bucket, media, logs, captures
        +--> VictoriaLogs        optional centralized log query
        +--> Kubernetes API      optional dynamic challenge instances
        |       |
        |       +--> challenge Pods / Services in ret2shell-challenge
        |       +--> image pull from registry / Docker Hub / GHCR / Harbor
        |
        +--> registry API        optional managed challenge image upload/search
        +--> SMTP / captcha / OAuth providers as optional integrations

平台服务可以运行在裸机、Docker Compose 或 Kubernetes 中。动态题目环境由 Kubernetes 编排，平台服务通过 kubeconfig 或集群内 ServiceAccount 访问 Kubernetes API。平台服务与题目容器可以位于同一个集群，也可以分别部署在不同环境中。

组件角色

组件	是否必需	关系与职责	替换与关闭方式
`ret2shell` 平台服务	必需	承载前后端、权限、比赛逻辑、题目实例控制、脚本执行入口和管理 API。	支持二进制、容器和 Helm 部署；前端静态文件可由平台内置静态服务托管，也可交给 Nginx、Caddy、Ingress 或 CDN。
PostgreSQL	必需	保存用户、队伍、比赛、题目、提交、公告、日历、配置、审计记录、OAuth 绑定等持久数据。	Helm 可使用内置 PostgreSQL，也可通过 `postgresql.mode = external` 指向云数据库或自维护数据库；该服务需要保持可用。
Valkey / Redis	必需	保存会话相关缓存、一次性令牌、接口限速状态、部分运行时缓存和短期状态。	Helm 可使用内置 Valkey，也可通过 `valkey.mode = external` 指向 Redis/Valkey、Redis Cluster 或 Sentinel 服务；该服务需要保持可用。
NATS JetStream	必需	提供后台任务和事件队列，平台用它处理邮件、事件落库、IP 记录、计分板更新、异常事件等异步流程。	Helm 可使用内置 NATS，也可通过 `nats.mode = external` 指向外部 NATS JetStream；该服务需要保持可用。
文件存储	必需	`bucket` 保存比赛/题目仓库、附件、checker、静态资源；`media` 保存用户上传图片；`log` 和 `captures` 保存本地日志和抓包/录制文件。	当前使用文件系统语义。裸机可使用本地盘或挂载盘，Kubernetes 中建议使用 PVC、CSI、NFS 等持久卷；这些目录需要和数据库一起备份。
Kubernetes	可选	题目需要在线环境时，平台通过 Kubernetes API 创建 `ret2shell-challenge` 命名空间下的 Pod 和 Service，并按标签清理过期实例。	可设置 `[cluster].enabled = false` 关闭动态容器能力。当前版本的动态题目环境以 Kubernetes 作为编排层。
Registry	可选	受控镜像仓库用于后台上传、搜索和代理挑战镜像，平台可通过 `/api/cluster/registry` 与前置网关暴露的 `/v2` 路径进行管理。	可使用 `registry.mode = internal` 部署内置 `registry:3`，也可用 `registry.mode = external` 接入 Harbor、云厂商仓库或自维护 Docker Registry。无需平台管理镜像时，可设置 `registry.mode = disabled` 或不配置 `[cluster.registry]`，并在题目 `env.toml` 中直接填写 Docker Hub、GHCR 等外部镜像地址，由 Kubernetes 节点直接拉取。
VictoriaLogs	可选	接收平台结构化日志，支撑后台日志检索、按 trace 查询和异常排查。	可使用 `victoriaLogs.mode = internal`，也可用 `victoriaLogs.mode = external` 指向已有 VictoriaLogs。设为 `disabled` 后，平台仍写本地日志；集中检索可由 Loki、ELK、云日志或节点侧采集器承接。
网关 / 反向代理	生产环境推荐	统一暴露 Web、API、WebSocket、大文件上传和可选 registry `/v2` 代理，同时负责 TLS、真实 IP、压缩和静态文件。	可使用 Nginx、Caddy、Kubernetes Ingress、云负载均衡或 CDN 回源；小规模内网测试也可直接暴露平台端口。
SMTP	可选	发送注册验证、找回密码等邮件。	`[email].enabled = false` 时关闭邮件能力；开启后可接入标准 SMTP 服务。
Captcha Provider	可选	平台内置 PoW/image 校验，也可接入 reCAPTCHA v3 或 hCaptcha。	可按 `[captcha].validator` 在 `none`、`image`、`pow`、`recaptcha_v3`、`h_captcha` 之间切换。
ret2script	内嵌能力	`ret2shell` 通过 Rune/ret2script 模块执行题目 checker、动态环境变量生成、流量映射脚本和生命周期脚本。	平台服务内置对应执行能力；`ret2script` 命令行主要用于题目作者在本地测试 `checker/main.rx`。
ret2boot	推荐部署入口	生产环境可用的交互式安装器，负责预检、Kubernetes/Helm/网关/平台部署规划和状态持久化。	适合单服务器快速部署；安装完成后无需常驻运行；复杂场景可以改用手工二进制、Docker Compose 或 Helm 部署。

“内置”表示 Helm 或 ret2boot 可以一并部署这些服务。PostgreSQL、Valkey、NATS 是运行必需项，并且都支持外置。Registry、VictoriaLogs、Kubernetes、SMTP、Captcha Provider 可按比赛需求启用、接入外部服务或关闭。

数据与控制流

常规访问路径

用户访问平台时，浏览器请求通常先到网关。网关把 / 路径交给静态前端，把 /api 和 WebSocket 请求转发给 ret2shell 平台服务。启用受控 registry 后，网关还可以把 Docker Registry 标准的 /v2 路径重写到平台的 registry 代理接口。

平台收到请求后会读取 PostgreSQL 中的业务数据，使用 Valkey 处理登录态、短期令牌和限速状态，并把耗时或需要异步传播的工作投递到 NATS JetStream。后台 worker 再从 NATS 拉取任务，例如发送邮件、记录事件、更新计分板或写入 IP 访问记录。

题目仓库与文件

比赛与题目文件同时依赖数据库和文件系统。bucket 目录保存题目结构、描述、附件、checker、环境配置和 Git 记录；media 目录保存平台上传图片；本地日志、抓包和录制文件也分别落在配置指定的目录中。灾备时需要把 PostgreSQL 和这些持久化目录纳入同一恢复点。

动态题目环境

题目配置了在线环境且 [cluster].enabled = true 时，平台会读取题目 env.toml，先用 ret2script/Rune 执行 environ() 生成动态环境变量，然后在 Kubernetes 中创建 Pod 与 Service。Pod 使用题目配置中的镜像地址，Service 根据外部暴露需求选择 NodePort 或 ClusterIP。

平台会给 Pod 和 Service 打上 ret.sh.cn/* 标签，用于按用户、队伍、比赛、题目和流量标识查询与清理。平台启动时还会确保存在 ret2shell-challenge 命名空间，并创建默认的 internet-disabled 网络策略，用于限制标记为不可联网的题目实例。

配置 traffic 脚本后，平台会把 Kubernetes Service 信息交给脚本的 expose() 函数，由脚本返回用户可见的访问地址。这个脚本可以对接你自己的网关、端口映射、反向代理、frp、云负载均衡或 DNS 规则；平台只负责把 Kubernetes 层的真实状态交给脚本。

镜像来源

Registry 是可选的镜像管理组件。启用 registry 时，平台可以提供镜像上传、仓库搜索和 /v2 代理能力，适合将比赛镜像纳入平台权限体系管理的场景。内置 registry 是 Helm/ret2boot 提供的默认实现，外部 Harbor、云镜像仓库、私有 Docker Registry 也可以承担同样角色。

无需平台管理镜像时，可以直接关闭 registry。此时题目环境仍然可以运行，只要 env.toml 里的镜像地址能被 Kubernetes 节点拉取即可，例如 docker.io/library/nginx:latest、ghcr.io/org/challenge:tag 或私有仓库地址。私有仓库认证应通过 Kubernetes 的 image pull secret 处理，并在题目环境配置中引用。

日志与审计

平台始终会写本地日志。配置 VictoriaLogs 后，结构化日志还会被批量写入 VictoriaLogs，后台的日志查询接口再代理 LogSQL 查询。NATS 中的事件用于平台内部状态传播和业务事件落库；VictoriaLogs 面向运维检索，NATS 面向平台内部异步流程。

关闭 VictoriaLogs 后，仍可通过本地文件、节点日志采集器或第三方日志平台观测服务。正式比赛通常建议保留一个集中式日志方案，尤其是开启动态环境、镜像上传或多管理员协作时。

常见部署形态

全部运行在 Kubernetes

这是 Helm chart 默认覆盖最完整的模式。ret2shell、PostgreSQL、Valkey、NATS、registry、VictoriaLogs 和持久卷都由同一个 Helm release 管理，平台通过集群内 ServiceAccount 控制题目命名空间。它适合已经接受 Kubernetes 运维模型、希望把平台和题目算力放在同一资源池中的部署。

平台在集群外，题目在 Kubernetes

平台可以用裸机或 Docker Compose 运行，通过 kubeconfig 访问外部 Kubernetes 集群。这个模式适合把平台服务、数据库和对象文件放在稳定主机上，把题目容器调度交给独立集群。此时要特别确认平台到 Kubernetes API、registry、VictoriaLogs、数据库、缓存和队列的网络连通性。

不启用动态题目环境

比赛题目无需在线容器时，可以关闭 [cluster].enabled。平台仍可承载账号、队伍、公告、Wiki、附件、提交、计分和静态题目内容；“启动实例”“容器日志”“流量映射”等功能随动态容器能力一同停用。此模式下 registry 通常也可以关闭，镜像仓库从平台运行路径中移除。

使用 ret2boot 引导

ret2boot 的定位是把上面的部署选择收敛成一个交互式安装流程：它收集公网入口、TLS、服务部署模式、存储模式、Kubernetes 发行版和 Helm values，再执行预检、集群初始化、网关部署和平台安装。它可以生成内置、外置或关闭可选组件的方案。安装完成后，平台运行时仍然遵循本页描述的组件关系。