高级配置 - FoxKiosk 文档

参数、批量与稳定性相关

1. 配置存在哪里、怎么改

配置本体存储于平台应用数据（SharedPreferences，键 app_config），不是散落的文本文件：

平台	位置
Windows	`%APPDATA%\<应用目录>\shared_preferences.json`
Android	应用私有目录 SharedPreferences
macOS / iOS	NSUserDefaults
Linux	`~/.local/share/<应用目录>/shared_preferences.json`

推荐改法：管理页或 POST /api/config（增量更新、热生效、自动校验）。手工改存储文件需先退出应用，且格式错误会被忽略并回退默认配置——非必要不手改。

用户文档目录 FoxKiosk/ 下存放的是数据文件而非配置：

FoxKiosk/
├── static/            上传的业务资源（/static/* 服务根）
├── config_page/       管理页部署目录（随包自动释放）
└── config_backup.json 配装备份（管理页备份功能生成）

2. 配置字段全表

字段	类型 / 默认	说明
defaultUrl	string / `http://localhost:19500/`	主页 URL，必填含协议
serverPort	int / `19500`	本地服务端口；被占用自动 +1 重试（最多 5 次）
enableCache	bool / `true`	WebView 缓存开关
orientation	string / `auto`	`landscape` / `portrait` / `auto`
preventExit	bool / `false`	退出保护开关
exitPassword	string / 空	退出密码
enableAudio / enableVideo	bool / `true`	媒体开关
userAgent	string / `FoxKiosk/1.0`	自定义 UA
disableContextMenu	bool / `true`	禁右键
disableShortcuts	bool / `true`	拦截快捷键
enableUserServer	bool / `false`	用户内容服务器开关
userServerPort	int / `8080`	内容服务器端口
userServerRoot	string / 空	内容服务器根目录（绝对路径）
autoStart	bool / `false`	开机自启（Windows）
fullscreen	bool / `true`	全屏
windowOnTop	bool / `true`	窗口置顶（桌面端）

3. 用户内容服务器（可选）

管理页 / API 开启 enableUserServer 并设置 userServerRoot 后，程序在 userServerPort（默认 8080）额外起一个静态文件服务，把指定目录独立成站。适合：业务页要引用大体积本地素材、或需要把「上传资源」与「内置配置服务」分开暴露的场景。关闭或根目录为空时该服务自动停止。

4. 生产环境安全加固

风险	措施
管理 API 无鉴权，同网段任何人可改配置	用防火墙 / VLAN 限制 19500 的可访问来源；绝不映射到公网
用户可切出程序	开启退出保护 + 设置退出密码；Android 启用屏幕固定 / 设备所有者；iOS 用 Guided Access / MDM
用户传恶意文件经 /static 传播	上传仅限可信管理员操作；`/static` 目录不上传可执行脚本类文件
配置被现场篡改	现场只留业务页；管理入口（长按右上角）不对外告知
日志泄露敏感信息	日志已自动脱敏（密码 / token / URL 凭据打码）

5. 运维排查

现象	排查
程序反复重启	看导出日志（`GET /api/logs/export`）最后几条 ERROR；常见为端口资源冲突或 WebView 初始化失败
19500 连不上	`netstat -ano \| findstr 19500`（Windows）确认监听；被占用时程序会顺延端口，以 `/api/network` 或启动日志为准
业务页加载慢 / 白屏	先普通浏览器验证网址本身；再管理页清缓存；HTTPS 证书无效会被 WebView 拦截
改了配置没生效	管理页保存即热生效；手改存储文件必须重启程序才读取
忘记退出密码	清除应用数据（Windows 删除 `%APPDATA%` 下应用目录的 shared_preferences.json）后重启，配置回默认

6. 构建与持续集成

管理页先行：config/ 下 yarn install && yarn build → dart run tool/build_assets.dart 打包为 app/assets/config_page.zip；
应用构建：flutter build windows|macos|linux|apk|ios（各平台依赖见仓库 tool/ci_build.sh）；
CI：GitHub Actions 自动构建 Linux 与 macOS / iOS；Android / Windows 走本地构建；Gitee Go 流水线配置见 .workflow/pipeline.yml。