convex-backend 自托管日志治理：REDACT_LOGS_TO_CLIENT 日志脱敏与 DISABLE_BEACON 遥测关闭指南

数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载自托管部署 convex-backend 时默认行为与云托管产品存在差异云产品会自动对返回给客户端的日志进行 PII 脱敏而自托管版本默认不开启同时自托管构建内含有一个用于帮助 Convex 团队了解产品使用情况的匿名 beacon 遥测。本文基于 self-hosted/advanced/disabling_logging.md 文档结合源码深入讲解如何通过REDACT_LOGS_TO_CLIENT与DISABLE_BEACON两个环境变量及等价 CLI 参数实现日志脱敏与遥测关闭并给出 Docker Compose、裸机直接运行等场景的完整配置方案。读完本文你将掌握在生产自托管环境中防止服务端堆栈信息泄露到客户端、以及彻底关闭匿名上报的两种标准做法。一、背景为什么自托管需要主动处理日志与遥测Convex 的云托管产品cloud-hosted product会自动对返回给客户端的日志进行脱敏redact以防止任何 PII个人身份信息泄露。但在自托管部署中这一层保护并不会自动生效——后端默认把函数日志、错误堆栈等信息按原始形态返回给调用方。与此同时自托管构建中包含一个 beacon信标用于帮助 Convex 团队了解产品使用情况。beacon 采集的信息是匿名且极简的仅包含一个随机标识符加上当前后端的版本号。虽然数据量极小但对于有严格合规要求或数据出境顾虑的企业仍然提供了明确的退出opt-out开关。这两项能力分别由两个环境变量控制环境变量默认值作用REDACT_LOGS_TO_CLIENT未设置等效 false置为true时对返回客户端的日志与错误信息进行脱敏DISABLE_BEACON未设置beacon 启用置为true时关闭匿名遥测上报二、REDACT_LOGS_TO_CLIENT开启日志脱敏防止服务端信息泄露2.1 文档定义与官方说明根据 disabling_logging.md云托管产品会自动脱敏日志以防止 PII 泄露。如果希望在自托管部署中也脱敏日志信息只需将环境变量REDACT_LOGS_TO_CLIENT设置为trueREDACT_LOGS_TO_CLIENTtrue2.2 源码级解析配置项从环境变量到生效链路在源码中该配置项定义于 crates/local_backend/src/config.rs/// If set, logs will be redacted from clients. Set this on production /// deployments, to prevent information like stacktraces of serverside /// code from being leaked to clients. /// /// On development deployments, it can be helpful to have this information /// reach the client for debugging purposes. #[clap(long, default_value false)] pub redact_logs_to_client: bool,从源码注释可以提炼出关键决策建议生产部署production应开启脱敏防止服务端代码的堆栈信息stacktraces泄露给客户端开发部署development可以保持关闭让服务端堆栈信息直接到达客户端便于本地调试。配置项以 CLI 参数--redact-logs-to-client的形式定义default_value false表示默认关闭。启动时该配置被注入到Application构造参数中见 crates/local_backend/src/lib.rsArc::new(RedactLogsToClient::new(config.redact_logs_to_client)),脱敏能力的核心实现在 crates/application/src/log_visibility.rs。它定义了一个LogVisibilitytrait核心方法为should_redact_logs_and_error——返回true时除非调用方具备管理员admin授权否则阻止日志到达客户端/// Trait for handling logging visibility. #[async_trait] pub trait LogVisibilityRT: Runtime: Send Sync { /// If true, then block logging from reaching clients unless they have /// admin authorization. async fn should_redact_logs_and_error( self, tx: mut TransactionRT, identity: Identity, allowed_visibility: AllowedVisibility, ) - anyhow::Resultbool; } pub struct RedactLogsToClient { redact: bool, } impl RedactLogsToClient { pub fn new(redact: bool) - Self { Self { redact } } } #[async_trait] implRT: Runtime LogVisibilityRT for RedactLogsToClient { async fn should_redact_logs_and_error( self, _tx: mut TransactionRT, _identity: Identity, _allowed_visibility: AllowedVisibility, ) - anyhow::Resultbool { Ok(self.redact) } }从实现可以看到自托管版本的判定逻辑非常直接redact字段为true则一律脱敏身份与可见性参数被忽略。这也解释了为什么生产环境开启后普通客户端请求拿到的错误与日志会被统一处理。2.3 脱敏的具体表现错误与日志双通道在 crates/application/src/lib.rs 的查询执行路径中should_redact_logs_and_error的返回值block_logging被同时作用于两个通道错误通道通过RedactedJsError::from_js_error(e, block_logging, request_id)构造脱敏后的 JS 错误返回日志通道通过RedactedLogLines::from_log_lines(query_return.log_lines, block_logging)处理函数产生的日志行。即开启脱敏后客户端收到的将是不含服务端堆栈细节的错误信息与日志行从而避免敏感代码路径、文件路径、依赖版本等内部信息的间接泄露。该判定同样被应用在 mutation、action、HTTP action 等多个执行入口crates/application/src/lib.rs 中共有 7 处调用点覆盖查询、变更及各类函数调用场景。三、DISABLE_BEACON关闭自托管匿名遥测3.1 文档定义与官方说明根据 disabling_logging.md自托管构建中包含一个 beacon目的是帮助 Convex 理解产品的使用情况。采集的信息匿名且极简仅包含一个随机标识符random identifier当前使用的后端版本version of the backend。如需退出将环境变量DISABLE_BEACON设置为true即可DISABLE_BEACONtrue3.2 源码级解析配置项定义与 beacon 生命周期配置项同样定义于 crates/local_backend/src/config.rs/// self-hosted Convex will periodically communicate with a remote beacon /// server. This is to help Convex understand and improve the product. /// If set, the self-host beacon will not be sent. #[clap(long, env DISABLE_BEACON, value_parser clap::builder::BoolishValueParser::new())] pub disable_beacon: bool,注意这里的env DISABLE_BEACON属性clap 会直接读取同名环境变量因此既可以通过环境变量设置也可以通过--disable-beacon命令行参数设置。BoolishValueParser意味着接受true/false等布尔风格取值。beacon 协程的实现位于 crates/local_backend/src/beacon.rs关键行为可以从源码确认上报频率成功上报后休眠一小时runtime.wait(Duration::from_secs(3600))再发下一次心跳失败重试采用指数退避Backoff::new(INITIAL_BACKOFF, MAX_BACKOFF)初始 1 秒上限 15 分钟上报内容database_uuid数据库 UUID即文档所述随机标识符、migration_version、compiled_revision编译时的 Git SHA即版本信息、commit_timestamp、uptime、beacon_tag等上报地址https://api.convex.dev/api/self_host_beacon。beacon 的启停逻辑在 crates/local_backend/src/lib.rsif !config.disable_beacon { let beacon_future beacon::start_beacon( runtime.clone(), database.clone(), config.beacon_tag.clone(), config.beacon_fields.clone(), ); runtime.spawn_background(beacon_worker, beacon_future); }从源码结构看disable_beacon为true时根本不会 spawnbeacon_worker后台任务即彻底不发起任何上报请求而非上报后再丢弃。四、实际配置方案三种部署形态4.1 方式一Docker Compose推荐项目提供的官方编排文件 self-hosted/docker/docker-compose.yml 已预留了DISABLE_BEACON与REDACT_LOGS_TO_CLIENT两个环境变量透传项你只需在宿主机环境或.env文件中设置即可无需修改 compose 文件environment: - DISABLE_BEACON - REDACT_LOGS_TO_CLIENT在启动 compose 前设置环境变量export DISABLE_BEACONtrue export REDACT_LOGS_TO_CLIENTtrue docker compose up -d或写入.env文件与 docker-compose.yml 同目录DISABLE_BEACONtrue REDACT_LOGS_TO_CLIENTtrue4.2 方式二官方 Docker 镜像的 run_backend.sh官方镜像的入口脚本 self-hosted/docker-build/run_backend.sh 会把两个环境变量翻译为对应的 CLI 参数exec ./convex-local-backend $ \ ... ${DISABLE_BEACON:--disable-beacon} \ ${REDACT_LOGS_TO_CLIENT:--redact-logs-to-client} \ ...这里采用了 Bash 的${VAR:value}参数展开语法只要DISABLE_BEACON非空例如设置为true就会追加--disable-beacon参数REDACT_LOGS_TO_CLIENT同理。也就是说只要这两个变量被设置非空即视为开启包括REDACT_LOGS_TO_CLIENT1、DISABLE_BEACONyes等写法都会生效并不严格要求字面量true。直接运行 Docker 容器时的等价写法docker run -d \ -e INSTANCE_NAMEmy-instance \ -e INSTANCE_SECRET你的密钥 \ -e DISABLE_BEACONtrue \ -e REDACT_LOGS_TO_CLIENTtrue \ -p 3210:3210 \ -p 3211:3211 \ ghcr.io/get-convex/convex-backend:latest4.3 方式三直接运行二进制裸机部署不经过镜像包装、直接运行编译产物的场景参见 running_binary_directly.md两个配置项对应如下 CLI 参数直接追加在启动命令中./convex-local-backend \ --instance-name my-instance \ --instance-secret 你的密钥 \ --convex-origin https://api.my-app.com \ --convex-site https://my-app.com \ --disable-beacon \ --redact-logs-to-client \ convex_local_backend.sqlite3同样也可以走环境变量形式clap 的env DISABLE_BEACON声明保证了两者等价export DISABLE_BEACONtrue export REDACT_LOGS_TO_CLIENTtrue ./convex-local-backend \ --instance-name my-instance \ --instance-secret 你的密钥 \ convex_local_backend.sqlite3五、验证与常见疑问5.1 如何验证脱敏已生效开启REDACT_LOGS_TO_CLIENT后可以在应用函数中故意抛出一个包含敏感信息的错误例如带有服务端文件路径的堆栈然后通过客户端 SDK 调用该函数观察返回的错误信息是否已不含堆栈细节。从源码逻辑看脱敏后的错误经由RedactedJsError::from_js_error(e, block_logging, request_id)构造crates/application/src/lib.rs日志行则经由RedactedLogLines::from_log_lines处理同文件 L1297两者在block_logging true时都会被改写。5.2 如何验证 beacon 已关闭DISABLE_BEACONtrue生效时crates/local_backend/src/lib.rs 中的分支不会执行日志中不会出现Starting beacon coroutine...该日志由 beacon.rs 在协程启动时输出。反之beacon 正常工作时每成功上报一次会输出一条包含sent successfully的 info 日志beacon.rs且该日志会明确提示可以通过--disable-beacon或DISABLE_BEACON关闭遥测。5.3 常见疑问QREDACT_LOGS_TO_CLIENT会脱敏服务端自己保存的日志吗不会。该开关只作用于返回给客户端的日志与错误通道LogVisibilitytrait 的语义即block logging from reaching clients服务端内部的日志记录如通过RUST_LOG控制的输出不受影响。需要进一步控制服务端日志输出时可参考 disabling_logging.md 之外的自托管高级配置文档如 hosting_on_own_infra.md。Q不开 beacon 会影响产品功能吗不影响。beacon 仅是匿名使用统计随机标识 版本号与数据库读写、函数执行、认证等核心功能完全解耦关闭它不会改变任何业务行为只影响 Convex 团队收集使用数据的能力。Q两个开关默认值是什么从源码看redact_logs_to_client的 clap 定义显式标注default_value falseconfig.rsdisable_beacon未标注默认值即 bool 类型默认falsebeacon 默认启用。因此生产自托管部署建议显式开启这两个开关而不是依赖默认行为。六、小结需求环境变量CLI 参数建议防止服务端堆栈/PII 泄露给客户端REDACT_LOGS_TO_CLIENTtrue--redact-logs-to-client生产环境必须开启开发环境可关闭以便调试关闭匿名使用统计上报DISABLE_BEACONtrue--disable-beacon有合规/隐私要求的部署建议开启两个开关都在 crates/local_backend/src/config.rs 中定义分别由 crates/application/src/log_visibility.rs 的RedactLogsToClient与 crates/local_backend/src/beacon.rs 的 beacon 协程承载实现。无论采用 Docker Compose、官方镜像还是直接运行二进制的方式部署 convex-backend均可通过环境变量或等价 CLI 参数一键完成日志脱敏与遥测关闭让自托管环境在隐私合规上与云托管产品对齐。赞分享数据库后端【免费下载链接】convex-backendThe open-source reactive database for app developers项目地址https://gitcode.com/gh_mirrors/co/convex-backend点击查看免费下载相关推荐Agent 治理工具包 ACS 遥测日志规范指南事件词汇、脱敏边界与 OTel 指标桥接Agent 治理工具包 ACS 遥测日志规范指南事件词汇、脱敏边界与 OTel 指标桥接 本篇技术指南围绕 agent governance toolkit人工智能AI AgentAI 安全治理策略引擎Agent 沙箱认证鉴权Numix图标主题常见问题解答解决硬编码图标和兼容性问题的10个技巧Numix图标主题常见问题解答解决硬编码图标和兼容性问题的10个技巧 Numix图标主题是Linux桌面环境中广受欢迎的开源图标主题为GNOME、XFCE、Reverie API完全指南掌握typed syscalls和异步处理机制Reverie API完全指南掌握typed syscalls和异步处理机制 Reverie是一个为Linux设计的符合人体工程学且安全的系统调用拦截框架它开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考