Fnos-Havline/README.md

# Havline fnOS 应用打包

本目录保存 Havline 的飞牛 fnOS 应用工程。

- 应用工程：[`havline/`](havline/)
- 官方工具：`fnpack`
- 当前工具版本：`1.2.3`
- 主程序仓库：`F:\Fonu-main\havline`

## 当前状态

已经完成：

- 使用 `fnpack create havline --template docker` 生成官方 Docker 应用骨架；
- 配置 `manifest`、应用入口、Docker Compose、权限和资源；
- 增加安装向导、配置向导和卸载向导；
- 增加安装、升级、配置和卸载生命周期脚本；
- 支持通过环境变量 `HAVLINE_INITIAL_ADMIN_PASSWORD` 初始化管理员。

仍需完成：

- 修复 Gitea Registry 的 HTTP token realm，使 Docker 能正常 push/pull；
- 确认飞牛设备是否可以匿名拉取，或在安装前配置 Registry 登录；
- 在飞牛测试设备验证安装、启动、入口、升级和卸载；
- 验证 amd64 与 arm64 镜像均可在真实设备上拉取。

## 当前阻塞

`jayhub.top/mrlee/havline:1.9.0` 已经包含 amd64 与 arm64 多架构索引，
但当前 Gitea 返回的认证地址仍是 HTTP：

```text
WWW-Authenticate: Bearer realm="http://jayhub.top/v2/token", ...
```

Docker 会在 HTTP 到 HTTPS 的跳转过程中丢失换取 token 所需的认证信息，
因此 `docker pull` 和 `docker push` 都会报：

```text
failed to fetch oauth token:
authorization server did not include a token in the response
```

在 Gitea `ROOT_URL` 改成 `https://jayhub.top/` 并确认反向代理传递
`X-Forwarded-Proto: https` 之前，飞牛设备无法稳定拉取该镜像。
详细修复步骤见主程序仓库：

```text
docs/gitea-registry-fix.md
```

## 镜像地址

当前应用使用：

```text
jayhub.top/mrlee/havline:${TRIM_APPVER}
```

对应标签需要包含：

```text
linux/amd64
linux/arm64
```

新地址已经使用 HTTPS，不需要再配置 `insecure-registries`。

验证镜像：

```bash
docker pull jayhub.top/mrlee/havline:1.9.0
```

如果仓库不是公开可拉取，先登录：

```bash
docker login jayhub.top
```

拉取成功后重新安装 `havline-1.9.0.fpk`。

## 打包

Windows PowerShell：

```powershell
cd F:\Fonu-main\fnos
.\build.ps1
```

脚本会先复制一份不含 `.DS_Store` 的干净工程，再调用 `fnpack` 打包，输出到：

```text
fnos/dist/havline-<version>.fpk
```

如果 `fnpack` 已在 PATH 中，也可以传入路径：

```powershell
.\build.ps1 -FnpackPath fnpack
```

## 测试安装

```bash
appcenter-cli install-fpk havline.fpk
```

安装后检查：

1. 应用中心显示 Havline；
2. Docker 镜像可以拉取；
3. Havline 容器能够启动；
4. 桌面入口可以打开管理界面；
5. 数据写入 `${TRIM_PKGVAR}`；
6. 卸载默认保留数据。

## 当前默认端口

| 用途 | 安装向导默认值 | 容器端口 |
| --- | ---: | ---: |
| 管理界面 | `6893` | `6893` |
| HTTP 反向代理 | `18080` | `80` |
| HTTPS 反向代理 | `9443` | `443` |

## 首发边界

- 不挂载 Docker Socket。
- 不启动 Havline 自带 updater。
- 不使用 host 网络。
- 不共享数据库、证书、密钥、Nginx、FRP 和 cloudflared 目录。
- 应用中心负责安装、升级、启动、停止和卸载。