# flatpakbackend

**Repository Path**: chairou/flatpakbackend

## Basic Information

- **Project Name**: flatpakbackend
- **Description**: flatpak的后端，用来定期自行更新
- **Primary Language**: Go
- **License**: BSD-2-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flatpakbackend

基于 libflatpak C API 的 HTTP/WebSocket 守护进程。前端（PyQt 软件商店）通过
`/ws/*` 接口下达全部读写指令；服务端持有 `FlatpakInstallation`，串行化所有
事务并把进度实时推回客户端。

## 安装依赖库

```bash
sudo apt update
sudo apt install -y \
  libflatpak-dev \
  libglib2.0-dev \
  libgirepository1.0-dev \
  gcc \
  pkg-config
```

## 编译

```bash
go mod tidy
go build -o flatpakbackend .
```

## 守护进程子命令

```bash
./flatpakbackend start                  # 后台启动（双 fork，立即返回）
./flatpakbackend status                 # 查看 pid / uptime / 文件路径
./flatpakbackend stop                   # SIGTERM 优雅停止，超时升级 SIGKILL
./flatpakbackend restart                # stop + start
./flatpakbackend foreground             # 前台运行，保留彩色输出，Ctrl-C 优雅退出
./flatpakbackend demo                   # 一次性演示流程（list/refresh/install/uninstall）
./flatpakbackend --help                 # 查看完整帮助
```

`start` 默认监听 `:8080`，可加 `--addr :9090` 改端口；`foreground` 同样支持。

### 文件位置

| 文件 | 路径 |
|---|---|
| PID  | `$XDG_RUNTIME_DIR/flatpakbackend.pid`（默认 `/run/user/<uid>/flatpakbackend.pid`），回退 `/tmp/flatpakbackend-<uid>.pid` |
| 日志 | `$XDG_STATE_HOME/flatpakbackend/server.log`（默认 `~/.local/state/flatpakbackend/server.log`） |

守护模式下 `\r` 进度条与装饰性 banner 自动静音，日志只留纯文本行。
`foreground` 模式保留全部彩色输出与进度条，便于本地调试。

### 周期刷新

设置环境变量 `REFRESH_TIME` 启用：服务端会按指定间隔自动调用
`flatpak_installation_update_remote_sync` 与
`flatpak_installation_update_appstream_full_sync`，结果写入日志（守护模式）
或终端（foreground）。

```bash
REFRESH_TIME=15  ./flatpakbackend start          # 每 15 分钟（纯数字 = 分钟）
REFRESH_TIME=5m  ./flatpakbackend start          # 每 5 分钟
REFRESH_TIME=2h  ./flatpakbackend foreground     # 每 2 小时
REFRESH_TIME=0   ./flatpakbackend start          # 关闭（默认）
```

兼容小写别名 `refresh_time`；小于 1 分钟会被夹紧到 1m，避免 OSTree 高频抖动。

### systemd 用户单元（可选）

如果想随登录会话自启，把 `start` 包进 systemd user service：

```ini
# ~/.config/systemd/user/flatpakbackend.service
[Unit]
Description=flatpakbackend WebSocket daemon

[Service]
Type=forking
PIDFile=%t/flatpakbackend.pid
ExecStart=/abs/path/flatpakbackend start
ExecStop=/abs/path/flatpakbackend stop
Restart=on-failure

[Install]
WantedBy=default.target
```

然后 `systemctl --user daemon-reload && systemctl --user enable --now flatpakbackend`。

## WebSocket 接口

完整接口清单与 wscat 示例见 [`docs/websocket-api.md`](docs/websocket-api.md)。

简要：

| 类别 | 路径 |
|---|---|
| 健康/锁 | `/ws/health` `/ws/lock/key` `/ws/lock/test` |
| 远程   | `/ws/remotes` `/ws/remotes/:remote/refresh` `/ws/remotes/refresh-all` `/ws/remotes/:remote/disabled` |
| 目录   | `/ws/catalog` |
| 应用   | `/ws/apps` `/ws/apps/install` `/ws/apps/updates` `/ws/apps/update-all` `/ws/apps/:appID/update` `/ws/apps/:appID/uninstall` `/ws/apps/:appID/permissions` `/ws/apps/:appID/info` |

健康探针保留为普通 HTTP：`GET /api/health`，方便负载均衡或 systemd 探活。