dsh-web/README.md

DSH 工作台（Android）

DSH Web Manager 的 Android 客户端：基于系统 WebView 的轻量壳应用，全部构建在 Docker 内完成，宿主机无需安装 Flutter/Android SDK。

特性

• 系统 WebView（webview_flutter），不打包浏览器内核，体积小
• 登录状态持久化：系统 WebView 的 Cookie + DOM 存储跨重启保留
• 全面屏适配：edge-to-edge、刘海/挖孔 shortEdges、深色启动底色无白闪
• 文件上传：<input type="file"> 走系统文件选择器（工作区上传、备份导入）
• 文件下载：拦截面板下载导航，交给系统 DownloadManager（携带登录 Cookie）
• 返回键：优先回退页面历史，无历史时退出应用
• 加载失败重试页、JS 原生对话框（alert/confirm）桥接

构建

前置：本机可用 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 构建上下文排除。密钥库和密码必须备份，覆盖升级需要保持包名与签名一致。

注意事项

• 证书：反代必须使用系统 WebView 信任的证书（如 Let's Encrypt）。自签证书会被拒绝，WebView 无法像浏览器那样手动放行。
• 签名：release 必须提供外部密钥库；缺失配置或密码/alias 不正确时构建失败，不回退到 debug 签名。此前的 debug 签名 APK 无法被新签名直接覆盖安装。
• Android 9 及以下：下载保存到应用外部目录（免存储权限），不进公共下载目录。
• 图标：使用仓库根目录的 logo.webp。API 26+ 使用浅冰蓝底色的自适应图标，旧系统使用同一 logo 的传统图标；各密度资源均已生成。