屏译 overlay-translator 安全与隐私设计指南:敏感设置加密存储、明文流量管控与崩溃日志脱敏
屏译 overlay-translator 安全与隐私设计指南:敏感设置加密存储、明文流量管控与崩溃日志脱敏
overlay-translator(屏译) 是一款无需 ROOT 的开源 Android 屏幕实时翻译工具,支持端侧与云端 OCR、离线 LLM 和多种翻译服务。除了翻译能力,它还在隐私上做了三条防线:敏感设置加密存储、明文 HTTP 流量白名单管控、崩溃日志脱敏。这篇文章用大白话讲清楚:你的 API Key、翻译配置和崩溃报告,是如何在这个应用里"各归其位"、不被泄露的。
一、屏幕翻译工具为什么需要隐私防线?
屏译要连接 OpenAI 兼容接口、DeepL、百度、腾讯等多家云服务,必然要保存大量 API Key、Secret、自架服务地址;同时它又鼓励用户连接自架的 deeplx、本地 OCR 服务,这些服务往往跑在家里 NAS 上,用的是不加密的 http://192.168.x.x。
这就产生了一对矛盾:既要让局域网服务可用,又不能放任明文流量流向公网。再叠加崩溃上报需求——用户闪退后需要"留现场",但现场里可能带着你的 Key。屏译的解法是把问题拆成三块,每块一条防线:
| 防线 | 防什么 | 核心实现 |
|---|---|---|
| 🔐 敏感设置加密存储 | 本机明文残留、导出泄露 | SettingsSecretCipher.kt |
| 🌐 明文流量管控 | 误把明文请求发到公网 | PrivateCleartextInterceptor.kt |
| 🩹 崩溃日志脱敏 | 反馈报告里夹带敏感字段 | CrashRecorder.kt |
💡 上图就是它的主场:悬浮窗实时抓取画面文字、翻译后叠加显示。正因为要"盯着"你的屏幕工作,密钥和数据的安全感才格外重要。
二、API Key 怎么加密保存?AndroidKeyStore + AES-GCM 实战
所有凭据在写入存储前都会过一遍加密,实现思路在 SettingsSecretCipher.kt 中:
- 密钥放在 AndroidKeyStore 里:由系统硬件级保护,应用读不出明文密钥,只用来加解密。密钥规格为 AES-256 / GCM 模式,随机 IV,别名
game_ocr_settings_secret_aes_gcm_v1。 - 密文带版本前缀:落盘格式是
enc:v1:+ Base64,未来换算法也能平滑迁移。 - 失败策略很关键(见 SettingsSecretCodec.kt):凭据加密失败时宁可存空值,也绝不回退明文——大不了重新填一次 Key,也不会泄露;非敏感字段才允许明文回退。
- 老用户自动迁移:应用启动时执行
migratePlaintextSecretsIfNeeded,把历史明文密钥自动搬进加密存储(入口在 GameOcrApp.kt)。
三、字段级策略:一张表决定谁能导出、谁必须脱敏
光加密还不够——导出配置包、写崩溃日志、搜索设置项时,不同字段待遇必须不同。屏译用一张"分类总表"统一管理全部设置字段,即 SettingsFieldPolicy.kt:
| 可携带性 | 示例字段 | 导出/诊断时的表现 |
|---|---|---|
PORTABLE 可随配置包迁移 |
源语言、字号、OCR 引擎 | 正常导出 |
CREDENTIAL 凭据 |
各类 API Key、Token | 不出现在导出包;诊断报告只显示 <set> / <empty> |
PRIVATE_CONNECTION 私有连接 |
自架服务 Base URL、镜像地址 | 仅摘要显示 |
RUNTIME_ONLY 运行时字段 |
前台应用上下文 | 直接省略 |
这样新增任何设置项都不可能"漏网"——它必须先进这张表。翻译预设的凭据更是单独加密存放、完全隔离在导出序列化器之外(SettingsRepository.kt)。所以下次备份配置到其他设备时,放心点导出:Key 只会留在原机。
四、明文 HTTP 白名单管控:公网必须走 HTTPS
这是屏译最有意思的安全设计,思路是"系统层放行 + 应用层把关"两步走:
- 系统层:network_security_config.xml 全局允许明文流量——目的是让你的
http://192.168.x.x:port局域网服务能用。 - 应用层:真正的安全边界是 OkHttp 拦截器 PrivateCleartextInterceptor.kt,规则非常干脆:
https://→ 直接放行;http://+ 本机localhost、回环地址、RFC1918 内网段、链路本地地址 → 放行;http://+ 公网主机名或公网 IP → 直接抛异常拒绝,并提示Cleartext HTTP only allowed for private/loopback addresses ... Use HTTPS for <host>。
如果你确实需要明文访问某台公网设备,可以在设置里加入白名单,但入口由 CleartextHostPolicy.kt 严格校验:只接受纯 host——带 https:// 前缀、端口号、路径、通配符 *、@ 或空格的条目一律打回。白名单变化还会被 GameOcrApp.kt 订阅并实时同步到拦截器,改完立即生效。
五、崩溃日志脱敏:留现场,但不带 Key
应用崩溃时怎么办?CrashRecorder.kt 挂了全局未捕获异常处理器,把"事故现场"写成 .crash 文件(最多保留 5 份),下次启动后进入日志页,由用户自己查看和导出——全程不联网、不自动上报。
脱敏体现在几个细节:
- 设置快照先脱敏再落盘:文件里的 Settings 段落来自第三节的分类表,凭据字段只显示
<set>,提示词类字段只显示<configured; N chars>,原始值一个字都不落盘; - 崩溃路径零 IO 风险:脱敏快照平时就缓存在内存里(
@Volatile),异常发生时直接读内存,避免在 DataStore 上做 IO 引发二次崩溃; - 原生崩溃也有据可查:API 30+ 通过
getHistoricalProcessExitReasons补上 Java 抓不到的 native crash、ANR、低内存退出;trace 限制在 16K 字符 / 64KB,二进制内容只记录 SHA-256 摘要和头部 16 字节十六进制(CrashRecorder.kt)。
六、调试日志也脱敏,以及给你的三点提醒
- Debug 构建会注册完整的 HTTP 网络日志拦截器(AppModule.kt),但里面的 DebugHttpLogSanitizer 会把
Authorization、Cookie、apikey、token、password、signature等敏感请求头、URL 查询参数、JSON/表单里的凭据字段全部替换成***;请求体只有完整捕获且不超过 64KB 才写日志,从机制上杜绝"截断半截泄露密钥"。 - Release 构建默认不注册该拦截器,正式包没有 wire log。
📌 小结:作为普通用户,你只需要记住三件事——
- Key 不出门:凭据用 AndroidKeyStore 加密,导出配置包、崩溃报告都拿不到它;
- 明文不出网:
http://只对你的内网和自己的白名单有效,公网一律强制 HTTPS; - 崩溃不上报:现场数据只存在本机日志页,发不发给维护者由你决定,且内容已脱敏。
想动手验证?打开设置页的日志与开发者选项,或查看源码中的 CleartextHostPolicyTest.kt、CrashRecorderExitTraceTest.kt 等测试,能看到每条防线的边界都被单元测试钉死了。


