dsh-web/README.md

DSH 工作台（Android）

DSH Web Manager 的 Android 客户端：使用随 APK 打包的 Mozilla GeckoView 内核，不依赖手机的系统 WebView。全部构建在 Docker 内完成，宿主机无需安装 Flutter/Android SDK。

特性

• 内置 GeckoView：Flutter 平台视图连接原生 GeckoSession，各设备使用同一发布版本的内核
• 登录状态持久化：使用非隐私 Gecko profile，持久 Cookie + DOM 存储跨重启保留（会话有效期仍由站点控制）
• 全面屏适配：edge-to-edge、刘海/挖孔 shortEdges、深色启动底色无白闪
• 文件上传：<input type="file"> 走系统文件选择器（工作区上传、备份导入）
• 文件下载：直接保存 Gecko 已认证请求的响应流，由系统“另存为”选择位置，不通过系统 WebView 获取 Cookie
• 下载状态通知：保存时显示进度和已下载大小，完成、失败或取消后更新状态；通知不提供打开文件或目录的操作。未知总大小时显示不定进度。Android 13+ 首次下载请求通知权限，拒绝不会阻止下载。
• 返回键：优先回退页面历史，无历史时退出应用
• 加载失败重试页、JS 原生对话框桥接

构建

前置：本机可用 Docker（构建通过代理访问 Google/Gradle 源时需在环境变量中提供 http_proxy/https_proxy）。

./build.sh https://panel.example.com --keystore /安全路径/dsh-release.jks --alias dsh-release

脚本做两件事：

1. 若本地没有 dsh-appbuilder:3.47.7 镜像，先构建它（Flutter 3.47.7 + Android SDK + 预热 Gradle/NDK 缓存，首次约 20–40 分钟）。
2. 在容器内执行 flutter build apk --release --split-per-abi --obfuscate。

产物在 build/app/outputs/flutter-apk/：

• app-arm64-v8a-release.apk：主流 64 位手机（一般装这个）
• app-armeabi-v7a-release.apk：老设备
• app-x86_64-release.apk：模拟器/ChromeOS

配置

站点地址由 build.sh 的第一个参数传入，通过 --dart-define=DSH_SITE_URL=... 编译进 APK，无需修改源码，应用启动时也无需输入。必须使用完整 HTTPS URL，可带端口和路径，不能带账号密码、空白、查询参数或片段。脚本在编译前验证地址并运行测试；地址不会写入 Docker 镜像。示例域名仅供说明，请替换为真实站点。

需要强制重建工具链镜像时，在上述命令后加 --no-cache。更换地址必须重新打包，已有 APK 不会自动更新。

Release 签名

--keystore 指向包含私钥的 JKS/PKCS12 密钥库（不是网站 TLS 证书，也不是仅含公钥的 .cer）；--alias 指定私钥条目。相对路径基于运行命令时的目录。脚本需要 Bash，密码默认隐藏输入，私钥密码回车时沿用密钥库密码。

CI 可通过 secret 管理器注入 DSH_STORE_PASSWORD 和 DSH_KEY_PASSWORD 环境变量；后者省略时沿用前者。不支持把密码作为命令参数。密码会传入临时容器环境，Docker 管理员可查看，因此仅在可信的 Docker 主机上构建。不要使用 shell 跟踪（bash -x）或把密码打印到日志。

密钥库以只读 bind mount 提供给容器，不复制进镜像。推荐把密钥库放在仓库外；常见密钥扩展名及 signing/ 已从 Docker 构建上下文排除。密钥库和密码必须备份，覆盖升级需要保持包名与签名一致。

注意事项

• 系统要求：当前 GeckoView 158 最低支持 Android 8.0（API 26），构建使用 Android SDK 37.0；旧 Android 设备不能安装此版本。已有工具链镜像可用 --no-cache 重建以预装新 SDK。
• 证书：反代必须使用 Gecko 信任的有效证书（如 Let's Encrypt）。不提供忽略 TLS 错误或自签证书放行开关。
• 签名：release 必须提供外部密钥库；缺失配置或密码/alias 不正确时构建失败，不回退到 debug 签名。此前的 debug 签名 APK 无法被新签名直接覆盖安装。
• 升级迁移：旧版系统 WebView 的 Cookie/LocalStorage 不会迁移到 Gecko；首次升级需重新登录，服务器端数据不受影响。
• 内核更新：GeckoView 版本固定在 android/app/build.gradle.kts，来自 Mozilla 官方 Maven 仓库。内核随 APK 发布，不会自动下载替换；应定期检查稳定版安全更新，更新版本并完成回归后发布新 APK。
• 开源许可：GeckoView/Gecko 包含 MPL 2.0 等许可证下的组件。分发 APK 时需保留上游许可声明并履行相应源码提供义务；参见 Mozilla 许可说明 与 GeckoView 项目。
• 体积：APK 包含 Gecko 原生库，体积会明显增加；继续按 ABI 分包，用户只安装匹配设备架构的 APK。
• 下载生命周期：保存过程中请保持应用运行；退出应用或进程被系统终止会中断下载，不提供系统 DownloadManager 的后台续传能力。
• 图标：使用仓库根目录的 logo.webp。API 26+ 使用浅冰蓝底色的自适应图标，旧系统使用同一 logo 的传统图标；各密度资源均已生成。

内核升级回归

发布前除 flutter analyze、flutter test 和 APK 构建外，应在真实 Android 设备上检查：

• 登录后重启应用，确认站点的持久登录状态及本地存储保留。
• 工作区单文件/多文件上传、选择器取消、配置备份导入。
• 需要登录的文件、目录 ZIP、配置备份下载，检查保存内容及取消流程。
• 下载通知：已知/未知总大小、多个下载、断网/保存失败、退出取消；Android 13+ 通知权限允许和拒绝，以及系统关闭通知的情况。
• JS alert/confirm/prompt、输入法、页面滚动、SPA 返回键、横竖屏及前后台切换。
• 断网重试与无效证书拒绝；确认没有绕过 TLS 校验。

Flutter 桥接单测不运行 Gecko 内核，不能替代上述真机测试。