跳转到内容
Viat

安全与秘密后端配置

安全与秘密后端配置

Section titled “安全与秘密后端配置”

使用主机运维权限设置环境；项目编辑权限不足以修改此处参数。账号与角色管理参见平台用户，激活参见实例激活。所有示例均未执行。

表格约定适用于本页。

变量类型；二进制默认值范围、作用域、覆盖与校验
VIAT_MASTER_KEYstring; required / 必填S。必须为 64 位十六进制（32 字节）。AES-GCM 主密钥；即便新秘密改用 Vault/AWS，仍然必填。项目不可覆盖。换值后旧 AES 密文无法解密。
VIAT_JWT_SECRETstring; dev-secret-change-meS。令牌签名字节；实现未强制最小长度。生产必须设强随机独立值；危险默认值只记录启动错误，不阻止启动。修改会使已签名令牌失效。
VIAT_ACCESS_TTL_SECONDSi64; 3600 sS。解析成功后优先于旧小时参数，否则尝试旧值/默认值。AppConfig 不强制正数，应配置正的有效期。
VIAT_TOKEN_TTL_HOURSi64; unset / 未设置S。已废弃；仅秒数缺失或解析失败时作为后备，乘以 3600 并警告。不强制正数，建议改用秒。
VIAT_REFRESH_TTL_SECONDSi64; 2592000 sS。30 天。AppConfig 不强制正数。影响后续有效期计算，不承诺重写已存过期时间。
VIAT_DEFAULT_ADMIN_EMAILstring; unset / 未设置S。非空邮箱启用初始 Owner 创建，并需要密码。已有账号不会因修改此值而重置密码或提升权限。
VIAT_DEFAULT_ADMIN_PASSWORDstring; unset / 未设置S。创建初始账号时配合邮箱使用；缺失/空值跳过并警告。确认正常管理入口后，从持续部署配置移除初始凭据。
VIAT_ALLOW_REGISTRATIONboolean; trueD。去空白后 false/no（忽略大小写）或 0 关闭，其余值开启。Docker 默认 false。控制平台注册，不替代项目终端用户策略。
VIAT_MFA_REQUIREDenum; offD。忽略大小写，admins/admin 要求平台高权限角色；all/true/1/yes 要求所有密码用户；其他值含拼错均为 off。不为每次 PAT/OIDC/API key 调用额外加 TOTP。
VIAT_LICENSE_CODEstring; unset / 未设置S。启动接纳与官方镜像匹配的有效激活码；无效/过期值记录日志并忽略，不降级已有更长期许可。未激活仍能启动但受锁定。
VIAT_EXPOSE_SCRIPT_ERRORSboolean; falseD。仅去空白后的字面值 1/true/yes 开启向调用方返回脚本错误详情。生产保持关闭；内部执行日志仍保留详情。
VIAT_OUTBOUND_DENY_PRIVATEboolean; falseD。去空白后 true/yes（忽略大小写）或 1 启用保存时 URL 主机检查。不是完整的 DNS 重绑定防御或网络沙箱，见下文。
VIAT_AUTH_RATELIMIT_IP_PER_MINUTEu32; 100 requests/minS。按认证路由/IP 的每分钟预算。0 关闭此桶。凭据限流在 PostgreSQL 持久化并跨节点共享。
VIAT_AUTH_RATELIMIT_IDENTITY_PER_MINUTEu32; 20 requests/minS。按认证路由/规范化身份限流。0 关闭此桶，不建议关闭；登录失败退避另行计算。
VIAT_SECRET_BACKENDenum; aes_gcmS。严格为 aes_gcm/vault/aws；空值也用 AES。未知值阻止启动。只决定新写入，不自动迁移既有秘密。
VAULT_ADDRURL; unset / 未设置S。只要存在就初始化 Vault，即便它不是写后端；必须非空。Vault 写入及读取旧 Vault 引用都需要。
VAULT_TOKENstring; unset / 未设置S。设置 VAULT_ADDR 时必填且非空。静态令牌，不自动续期。仅授予指定 KV v2 范围的读取/创建/更新权限。
VAULT_KV_MOUNTstring; secretS。KV v2 挂载名称，不是完整 /v1/data URL。修改可能使旧引用无法读取。
VIAT_VAULT_PATH_PREFIXstring; viatS。新值写入 prefix/UUID 路径；旧引用保留自身路径。历史前缀仍需读取权限。
VIAT_SECRETS_AWSswitch; unset / 未设置S。只有严格的 1 才初始化 AWS Secrets Manager。AWS 写入及读取旧 AWS 引用都需要；true 不会启用。
VIAT_AWS_SM_NAME_PREFIXstring; viat/S。新 Secrets Manager 名称前缀。AWS SDK 的区域/凭据链与 Rust S3 产物凭据不是一组配置。
VIAT_WORKER_DROPboolean; on / 开启F；仅 Unix。字面值 0/false/no 关闭降权。仍需要有特权的父进程及可解析的非 root 目标。Docker 父进程是 root，worker 为 10001/10001。
VIAT_WORKER_UIDu32; unset / 未设置F；仅 Unix。显式非零正 UID 优先于账号查询。非法或 0 会警告并让 worker 保持服务端身份，不会强制阻止启动。
VIAT_WORKER_GIDu32; explicit UID / 显式 UIDF；仅 Unix。仅配合显式 UID 使用；缺失/非法时使用 UID 数值。仍受操作系统权限限制。
VIAT_WORKER_USERstring; viatF；仅 Unix。未设 UID 时查询此账号；账号不存在或是 root 则不降权并警告。非特权服务端不能变更 worker UID。
VIAT_WORKER_DATA_DIRSstring; unset / 未设置S。冒号分隔、已存在的绝对目录，不能是 /。按工作账号递归接管属主，受符号链接/属主检查限制。不要列入不允许改属主的共享宿主目录。

主密钥、JWT 与初始账号

Section titled “主密钥、JWT 与初始账号”

用私密终端中的 openssl rand -hex 32 生成独立主密钥和 JWT 随机值，放进受限服务环境。命令仅为示例；不要复制示例密码。主密钥与数据库备份分开保管并演练共同恢复。JWT 值相同的多个节点可识别同一组令牌；随机换一台节点的密钥会造成间歇性登录/解密失败。

初始 Owner 只在账号不存在时创建。修改 VIAT_DEFAULT_ADMIN_PASSWORD 不能重置已有账号密码，也不会把已有低权限用户提升为 Owner。关闭注册前先确认可用 Owner、OIDC 或恢复通道。设置 VIAT_MFA_REQUIRED=admins 前先让受影响人员登记验证器并离线保管恢复码；all 会扩大受影响范围。MFA 必需策略拼错会关闭强制要求，不会给出安全的拒绝启动。

AES、Vault 与 AWS 的实际操作

Section titled “AES、Vault 与 AWS 的实际操作”
  • AES-GCM：默认；密文在平台 PostgreSQL，解密依赖原 VIAT_MASTER_KEY。
  • Vault KV v2：先准备 KV v2 mount、TLS 信任和受限 token，再设置以下参数；示例不创建真实秘密。
VIAT_SECRET_BACKEND=vault
VAULT_ADDR=https://vault.example.com:8200
VAULT_TOKEN=REPLACE_WITH_SCOPED_TOKEN
VAULT_KV_MOUNT=secret
VIAT_VAULT_PATH_PREFIX=viat

平台写入 /v1/secret/data/viat/UUID，JSON 为 {"data":{"v":"BASE64_VALUE"}}；读取同一路径，期望 data.data.v。Base64 不是加密，依赖 Vault 自身安全。token 不自动续期；续期/轮换和进程重启由运维负责。该客户端显式不使用环境代理。

  • AWS Secrets Manager：设置 VIAT_SECRETS_AWS=1 和 VIAT_SECRET_BACKEND=aws；使用 AWS SDK 默认凭据/区域链（优先采用受限工作负载身份）。以 VIAT_AWS_SM_NAME_PREFIX 限制可创建/读取的名字；至少需要对应 CreateSecret、GetSecretValue，如配置 KMS 则须相应密钥权限。不要把 Rust 产物存储的 VIAT_RUST_S3_* 当作 Secrets Manager 凭据。

后端标记随每个 blob 保存：0x01 AES、0x02 Vault 路径、0x03 AWS 秘密名。改变写后端不会重加密旧数据。迁移/回退期间保留所有历史读取后端、mount、密钥和权限。恢复数据库而未恢复外部秘密，会留下不可用引用。禁止假设删除资源会替你清理所有历史外部秘密；生命周期清理由备份/合规策略另行安排。

在隔离项目写入一个测试秘密并通过合法资源调用验证读取；不要把秘密打印到日志。失败时检查 blob 对应后端、token 过期、区域/权限、路径/mount 和网络；恢复旧读取配置，不要覆盖密文“修复”。

重要：凭据投射并非绝对隔离

Section titled “重要：凭据投射并非绝对隔离”

平台会清空工作进程环境并禁止透传核心平台密钥，许多资源通过平台侧代理调用并屏蔽已知秘密。但是 1.1.0 部分数据库、缓存、AMQP、S3 资源对象仍向脚本投射凭据。因此不能宣称“所有资源秘密永远不会进入脚本”。开发者能够执行代码，应按其可访问资源的敏感级别授信；日志屏蔽不等于阻止主动外传，也不能替代最小权限资源账号。

容器默认 UID 分离只能减少同 UID 的 /proc 读取风险，不是任意恶意代码的完整沙箱。没有工作账号、显式错误 UID、非 root 父进程或禁用降权，都可能让 worker 与服务端同身份。生产必须核对启动日志，并限制容器内存/PID、挂载、网络出口和主机权限。Rust 编译可执行构建脚本，编译主机也是敏感信任边界。

VIAT_OUTBOUND_DENY_PRIVATE 只是选定保存路径的主机校验；不解析所有 DNS 结果，也不约束脚本任意 socket。对不可信作者用网络防火墙/隔离实例实施策略。完整操作清单见安全运维。