Octop/fnos

Octop — 飞牛 FnOS 安装包

本目录包含将 TencentCloud/Octop 打包为飞牛 fnOS .fpk 安装包所需的全部文件，并附带自动同步上游 + 自动构建的 GitHub Actions。

首次使用（初始账号）

安装向导中设置管理员账号与密码，两种方式任选：

1. 自己输入密码 —— 至少 8 位，且必须同时包含字母和数字（与应用侧密码策略一致；过于常见的密码如 Octop123 会被拒绝，无效输入会在安装时直接提示，不会装完才失败）。
2. 自动生成随机密码（推荐） —— 安装时自动生成 16 位强密码。

生成的 / 设置的密码通过以下两种方式双保险送达用户：

• 应用「设置」窗口：飞牛应用中心 → Octop → 设置，窗口顶部直接显示当前管理员账号与密码，也可在此随时改密（保持不变 / 随机生成 / 自己设置）；
• 回落备份文件：数据共享目录下的 octop-login.txt（本地版在 data-share 共享目录，Docker 版在 /var/apps/octop/share/octop/data/），永久保留并随改密同步更新。

若你在 Web 控制台「头像菜单 → 修改密码」中改过密码，则以 Web 密码为准（octop-login.txt 与「设置」窗口显示的是安装/配置阶段写入的凭据）。

官方命令行管理

本地版安装后自动注册官方 CLI 到 PATH（/usr/local/bin/octop → octop-cli），SSH 进飞牛即可使用全部官方管理命令（以 root 或 octop-native 身份执行最顺）：

octop --help            # 官方 CLI 全部子命令
octop version
octop provider list     # 模型 provider
octop agent list        # 专家/Agent
octop user list         # 用户管理
octop user passwd <用户名> --password <新密码>   # 离线改密（应用「设置」窗口改密也走这一命令）
octop skills --help     # 技能管理
octop backup --help     # 备份/恢复

注意：不要手动执行 octop run（会与飞牛应用中心托管的服务实例抢 8089 端口）；Web 服务一律由应用中心启停。

两种安装包

仓库同时产出 两款 .fpk，用于满足不同部署偏好：

版本	包名	体积	运行方式	依赖
Docker 版	Octop-fnos-docker-<ver>.fpk	~8 KB	飞牛自动从 GHCR 拉取 ghcr.io/tencentcloud/octop:latest 镜像运行	宿主需有 Docker 运行时
本地版（非 Docker）	Octop-fnos-native-<ver>.fpk	~560 MB	自带 Python 3.12 运行时 + 前端 + 核心依赖，原生运行在飞牛主机	无需 Docker

• Docker 版实现为 FnOS docker-project：包体只含 docker-compose.yaml 与向导配置，运行时由飞牛从 GHCR 拉取镜像。镜像已内置 desktop 桌面控制与前端；Playwright Chromium 不预装，可在控制台按需安装。
• 本地版实现为 FnOS 原生 app：包内自带独立 Python 3.12 运行时、Octop 核心依赖、前端构建产物，以及 data-share 共享数据目录，直接以进程方式运行，不依赖 Docker。

两款包随正式版一起挂在 v* GitHub Release 上（例如 v0.9.31）：Octop-fnos-docker-<ver>.fpk / Octop-fnos-native-<ver>.fpk。

目录结构

fnos/
├── README.md
├── docker/                 # Docker 版（docker-project）
│   ├── manifest            # 应用元信息（platform=all / 名称/版本/桌面入口等）
│   ├── ICON.PNG / ICON_256.PNG
│   ├── LICENSE             # 复用仓库根 LICENSE（MIT）
│   ├── cmd/                # 生命周期脚本（main / install_callback / config_callback 等）
│   ├── config/
│   │   ├── privilege       # 权限声明（docker-octop 用户）
│   │   └── resource        # 资源声明（docker-project + 数据共享目录）
│   ├── wizard/
│   │   ├── install       # 安装向导（管理员账号/密码：自输或随机生成、日志级别、LLM 密钥）
│   │   ├── config        # 应用「设置」窗口（当前密码显示 + 改密 + 日志级别 + LLM 密钥）
│   │   └── uninstall     # 卸载向导（数据清理方式）
│   ├── app/
│   │   ├── docker/
│   │   │   └── docker-compose.yaml   # 引用 ghcr.io/tencentcloud/octop:latest
│   │   └── ui/
│   │       ├── config                # 桌面图标入口
│   │       └── images/icon-{64,256}.png
│   └── Dockerfile          # 从仓库源码构建镜像，安装 desktop extra（不预装 Chromium）
└── native/                 # 本地版（非 Docker 的 FnOS 原生 app）
    ├── manifest            # platform=all + 原生 app 元信息
    ├── cmd/                # 生命周期脚本（main / install_callback / config_callback）
    ├── config/
    │   ├── privilege       # 权限声明（root，用于 sudo / 远程桌面等）
    │   └── resource        # data-share + usr-local-linker
    ├── app/
    │   ├── bin/octop       # 启动器（用自带 Python 运行时启动 octop init/run，init 带弱密码自动重试兜底）
    │   ├── wizard/config.template   # 「设置」窗口表单模板（渲染当前密码后落到已安装包 wizard/config）
    │   └── ui/             # 桌面图标入口
    └── wizard/             # 安装/配置/卸载/升级向导

工作机制

1. 发版链路：v* tag → release.yml（PyPI + GitHub Release）与 docker-publish.yml（GHCR / Hub）并行；Release 成功后自动 workflow_dispatch 本工作流。
2. 镜像复用：不再重新 build 镜像；ensure-image 轮询等待 ghcr.io/tencentcloud/octop:{version}（由 docker-publish 推送）。Docker 版 .fpk 仅打包 compose，运行时拉取该镜像。
3. Wheel 复用：Native 版优先从同版本 GitHub Release（v*）下载 octop-*.whl；若缺失再回退源码构建前端 + wheel。
4. 安装包构建：fpk / native job 用 scripts/build-fpk.sh 打包，产物 Octop-fnos-docker-<ver>.fpk / Octop-fnos-native-<ver>.fpk 挂到同一个 v* GitHub Release（与 wheel、桌面包并列）。

本地构建 .fpk（无需 Docker）

bash scripts/build-fpk.sh            # 仅 Docker 版  → dist/Octop-fnos-docker-<version>.fpk
bash scripts/build-fpk.sh docker     # 仅 Docker 版
bash scripts/build-fpk.sh native     # 仅本地版      → dist/Octop-fnos-native-<version>.fpk

.fpk 为「双层 gzip tar」：外层含 app.tgz / cmd / config / wizard / ICON.PNG / ICON_256.PNG / LICENSE / manifest，内层 app.tgz 含 app/ 内容。

在飞牛上安装

1. 飞牛「应用中心 → 设置 → 手动安装应用」选择对应 .fpk：
   • 想用 Docker 跑、主机已装 Docker → 选 Octop-fnos-docker-<version>.fpk
   • 不想依赖 Docker、希望自带运行时原生运行 → 选 Octop-fnos-native-<version>.fpk
2. 安装向导中设置管理员账号/密码、日志级别、LLM 密钥（可选）。
3. 安装完成后桌面出现「Octop AI 助手」图标，浏览器打开 http://<设备IP>:8088。
4. Docker 版镜像首次会从 GHCR ghcr.io/tencentcloud/octop:latest 拉取；请确保该包为 Public（首次推送后可在 GitHub Packages 设置）。本地版无需联网拉镜像。Playwright Chromium 不预装，需要远程浏览器时在控制台按需安装。

服务端口固定为 8088（飞牛端口映射与桌面图标均据此）。desktop 桌面控制已在镜像中默认安装。