54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
# 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`）。
|
||
|
||
```sh
|
||
./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 的传统图标；各密度资源均已生成。
|