跳转到内容
Viat

网络、TLS 与部署输入

网络、TLS 与部署输入

Section titled “网络、TLS 与部署输入”

本页包含应用监听参数及非应用安装输入。总览表约定适用；除条件要求外均可选。所有部署/代理示例未执行。

服务端与 WebSocket 参数

Section titled “服务端与 WebSocket 参数”
变量类型；默认值校验、作用域与优先级
VIAT_BINDstring; 0.0.0.0:8080S。监听地址；内置 TLS 要求可解析的 IP:port SocketAddr。反代后选择回环/私网地址。Docker/部署脚本可显式设置。
VIAT_PUBLIC_URLURL; unset / 未设置S + D。去空白和末尾斜杠；路径作为挂载前缀。不设时从 Host/X-Forwarded-Proto 推导。未做统一严格 URL 校验，应提供可信绝对 URL。项目不可覆盖。
VIAT_TRUST_PROXY_HEADERSboolean; falseF。去空白且忽略大小写的 true/yes 或 1 启用转发客户端 IP；仅在所有请求经过可信且清理头的代理时安全。
VIAT_TLS_CERTpath; unset / 未设置S。PEM 证书/完整链，须配 key。空值视为未设。每 60 秒检查修改时间并重载文件内容；路径变更须重启。
VIAT_TLS_KEYpath; unset / 未设置S。与证书匹配的 PEM 私钥；只设置一边或首次加载失败会阻止启动。后续重载失败保留旧证书。
VIAT_WEB_DIRpath; unset / 未设置S。含可读 index.html 的控制台构建目录。Docker 为 /app/web。目录无效会警告并不提供控制台。
VIAT_UI_ENABLEDboolean; trueS。去空白后的 false/no（忽略大小写）或 0 禁用控制台，API 不受此开关关闭。没有目录时开启也不提供 UI。
VIAT_DOCS_DIRpath; unset / 未设置S。含可读 index.html 的已渲染手册目录。Docker 为 /app/docs。用于 /_docs，不是远程文档 URL。
VIAT_DOCS_ENABLEDboolean; trueS。与 UI_ENABLED 同一解析规则，独立关闭内置 /_docs。
VIAT_WS_MAX_CONNECTIONSu64 → usize; 10000 connectionsF。单实例 WebSocket 连接正上限；0/非法回退。不是整个集群的上限。
VIAT_WS_MAX_MESSAGE_BYTESu64 → usize; 65536 bytesF。正的 WebSocket 入站消息上限（64 KiB）。
VIAT_WS_QUEUE_DEPTHu64 → usize; 32 messagesF。每连接正的出站队列深度；慢消费者可能被关闭，避免无限占内存。
VIAT_WS_REVALIDATE_SECSu64; 300 sF。正的会话/授权复核间隔，不保证凭据立即撤销。
VIAT_WS_MAX_LIFETIME_SECSu64; 86400 sF。正的连接寿命上限（24 小时）；客户端须重连并重新认证。

Compose 与部署脚本控制

Section titled “Compose 与部署脚本控制”
变量类型；默认值校验、作用域与优先级
VIAT_TAGstring; latestI，仅 Compose。选择镜像标签；生产固定 1.1.0 或已批准摘要，而非易变 latest。
VIAT_PORTport mapping; 8080I，仅 Compose。宿主发布端口；容器内仍为 8080。由 Docker 校验映射。
POSTGRES_USERstring; viatI，示例 PostgreSQL 镜像初始化及拼接 DATABASE_URL；已有卷上修改不会重命名/创建账号。
POSTGRES_PASSWORDstring; viatI，示例 PostgreSQL 初始化和 URI 替换。必须换掉不安全默认值；修改不会轮换已有数据库账号密码。
POSTGRES_DBstring; viatI，示例 PostgreSQL 初始化及 URI；已有卷不重新初始化。
ENV_FILEpath; scripts/.envI，部署脚本。加载前选择，文件必需且是可执行 shell 语法。仅转发此文件声明的非脚本专用键。
IMAGEimage reference; official :latestI，部署脚本。非空调用环境 > 文件 > 默认。应固定稳定产物，不保证自动兼容数据库模式。
IMAGE_TARpath; unset / 未设置I，部署脚本。非空时导入本地镜像包并跳过登录/拉取；IMAGE 须匹配导入镜像。调用环境优先。
NAMEstring; viat-serverI，部署脚本。容器名；同名现有容器会被强制删除并重建。调用环境优先。
HOST_PORTport mapping; 8080I，部署脚本。宿主映射到固定容器端口 8080。调用环境优先；反代后可用 127.0.0.1:8080。
PULLswitch; 1I，部署脚本。无 IMAGE_TAR 时严格 1 才拉取；0 使用本地镜像。调用环境优先。
UV_CACHE_VOLUMEmount; viat-uv-cacheI，部署脚本。挂载到 /home/viat/.cache/uv。调用环境优先；不是应用 UV_* 包管理设置。
READY_TIMEOUTinteger; 60 sI，部署脚本。shell 循环等待 HTTP /auth/config，不是 /readyz 或脚本环境就绪。使用正数秒；调用环境优先。
DOCKER_NETWORKstring; unset / 未设置I，部署脚本。已存在 Docker 网络；调用环境优先。用于数据库/容器名连通。
EXTRA_MOUNTstring; unset / 未设置I，部署脚本。逗号分隔 Docker -v 规格。调用环境优先。尽可能只读，不挂宿主 socket 或根目录。
SECURITY_OPTstring; unset / 未设置I，部署脚本。逗号分隔 Docker security-opt；调用环境优先。seccomp=unconfined 削弱隔离，不是生产默认。
PIDS_LIMITDocker limit; 512I，部署脚本。容器进程/线程上限，由 Docker 校验。实际实现先接收调用环境再加载文件，因此文件可覆盖调用值。不是应用并发。
MEMORY_LIMITDocker size; 4gI，部署脚本。容器内存上限，由 Docker 校验。当前实现文件可覆盖调用值。只是示例起点，不是容量建议。
REGISTRY_HOSThost[:port]; derived / 推导I，部署脚本。未显式设置时从 IMAGE 推导仓库；调用环境优先。不注入应用。
REGISTRY_USERNAMEstring; unset / 未设置I，部署脚本。执行登录且使用密码时需要；调用环境优先。Docker 在部署主机保存登录凭据。
REGISTRY_PASSWORDstring; unset / 未设置I，部署脚本。配对登录秘密，经 password-stdin 传入，不进入应用环境。下项密码文件优先。调用环境优先。
REGISTRY_PASSWORD_FILEpath; unset / 未设置I，部署脚本。可读密码文件覆盖 REGISTRY_PASSWORD，须限制权限。调用环境优先。
REGISTRY_LOGINswitch; 1I，部署脚本。拉取路径严格 1 才登录；0 跳过并用已有 Docker 凭据/匿名访问。调用环境优先。

公共 URL、前缀与反向代理

Section titled “公共 URL、前缀与反向代理”
VIAT_PUBLIC_URL=https://api.example.com/viat
VIAT_TRUST_PROXY_HEADERS=true

这表示外部端点为 https://api.example.com/viat/p/PROJECT/PATH，控制台为 /viat/ui/。VIAT_PUBLIC_URL 路径就是前缀；没有第二个受支持的前缀变量。代理可以保留前缀让服务端剥离，也可以只剥离一次；不要重复添加/移除。更新 IdP 注册回调和外部 webhook URL；避免选用与内部平台路径冲突的前缀。

显式公共 URL 固定出站链接使用的 origin，并避免代理忘记 X-Forwarded-Proto 时把 HTTPS 猜成 HTTP。它不替代 TLS、不开放端口、不验证代理可信度。所有请求必须经过受控代理且代理应覆盖客户端提供的转发头，再开启 VIAT_TRUST_PROXY_HEADERS。IP 读取优先取 X-Forwarded-For 最后一段，再考虑 X-Real-IP；多层代理必须按实际链路验证，不能盲用第一段。

完整 TLS/流式/WebSocket 代理示例、证书续期与校验见 TLS 与反代。

不可忽略的固定限制

Section titled “不可忽略的固定限制”
  • 交给脚本/工作流缓冲的普通请求体上限 2 MiB，不是可任意提高的环境变量。multipart 文本字段合计也受该预算；文件部分使用磁盘暂存和文件上限。
  • 反代/专用 S3 流式传输不是同一缓冲路径。代理应单独配置请求大小和磁盘预算，而不是把所有路径无限放大。
  • Rust 产物上传上限 512 MiB。可上传不等于适合通过任意前置代理；还受代理限制和授权。
  • WebSocket 默认每实例 10,000 连接不代表承诺容量；每个队列和消息都消耗内存。代理须支持 Upgrade，并为流式/SSE 禁用不必要的缓冲。
  • 镜像健康检查每 30 秒执行，超时 3 秒、启动期 20 秒、失败 3 次；探测 /healthz，不校验公网证书身份，也不等于 /readyz。

部署脚本的真实副作用

Section titled “部署脚本的真实副作用”

deploy-server.sh 依赖已经存在的 PostgreSQL，不创建数据库；读取可信 .env、按需登录仓库/导入或拉取镜像，然后强制删除旧容器并启动新容器，不是无中断滚动更新器。其检查只等待明文 http://127.0.0.1:HOST_PORT/auth/config；内置 TLS、特殊绑定或网络映射需要另行验证，不能据此判定不可用。

脚本默认容器端口 8080、缓存卷及资源限额；最终也会传入文件中声明的应用变量，应避免在脚本模式配置冲突的 VIAT_BIND。非脚本键若仅存在于调用者 shell 而未在文件声明，不会自动转发。ENV_FILE 是 shell source 输入，只加载可信文件，绝不运行下载来的未知脚本。

镜像构建输入 DEBIAN_SUITE（默认 bookworm）、VITE_MONACO_BUNDLE（true；false 不再受支持）、RUSTUP_DIST_SERVER/RUSTUP_UPDATE_ROOT（未设时官方工具链下载）均为 I，构建时。VITE_BASE=./ 是官方镜像资产相对路径；VITE_VIAT_API_URL 是自建前端构建输入，不是部署后修改 API origin 的服务器开关。详见客户端与工具链分类。