FlatpakCN/LocalServer

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

The repository has been archived and is now in read-only mode.

main

LocalServer/README.md

SiemYan

update

073a234c

PreviewCode viewBlame

Flatpak LocalServer

一个基于 Flask 的 Flatpak 管理 API 服务器，提供了 RESTful API 接口来管理 Flatpak 应用程序，支持安装、卸载、更新、搜索等操作，并具备任务队列管理功能。

快捷安装


# 一键安装（推荐）
curl -fsSL https://flatpak.cn/install.sh | sudo bash

# 或使用 wget
wget -qO- https://flatpak.cn/install.sh | sudo bash

功能特性

核心功能

📦 应用管理：安装、卸载、更新 Flatpak 应用
🔍 搜索功能：搜索可用的 Flatpak 包
📋 应用列表：查看已安装的应用和运行时
▶️ 运行应用：直接启动已安装的 Flatpak 应用
🌐 远程仓库管理：添加、删除和列出远程仓库

任务管理

⏳ 任务队列：异步处理耗时操作
📊 实时状态：获取任务执行状态和进度
📝 日志记录：实时查看任务执行日志
❌ 任务取消：取消待处理的任务
🧹 任务清理：清除已完成的任务记录

技术特性

🔄 CORS 支持：允许跨域请求
🧵 多线程处理：后台工作线程处理任务队列
🔒 线程安全：使用锁机制确保数据一致性
📡 实时输出：流式获取命令执行输出

系统要求

Python 3.6+
Flatpak
Linux 操作系统

快速安装

🚀 一键安装（最快）

直接从网络下载并安装，无需克隆仓库：

使用 curl：


curl -fsSL https://flatpak.cn/install.sh | sudo bash

使用 wget：


wget -qO- https://flatpak.cn/install.sh | sudo bash

或者两步验证安装（更安全）：


# 1. 下载安装脚本
curl -fsSL https://flatpak.cn/install.sh -o install.sh

# 2. 查看脚本内容（可选，建议）
less install.sh

# 3. 执行安装
sudo bash install.sh

💡 提示：一键安装会自动从服务器下载所需文件，无需手动下载项目。

方式一：自动安装（推荐）

如果您已经下载或克隆了项目，可以直接运行安装脚本：


# 运行安装脚本
sudo ./install.sh

安装位置：程序将被安装到系统目录 /opt/.FlatpakCN

安装脚本会自动：

✅ 检测Linux发行版（支持 Ubuntu/Debian、Fedora、Arch Linux 等）
✅ 安装系统依赖（Python3、Flatpak）
✅ 安装Python依赖（Flask、Flask-CORS）
✅ 检测已安装版本，支持升级/降级确认
✅ 复制文件到系统目录 /opt/.FlatpakCN
✅ 创建并启用 systemd 服务
✅ 设置开机自启动
✅ 启动服务

版本检测：安装前会自动检测已安装版本，如果已安装相同版本会询问是否重新安装，如果是升级或降级也会进行提示确认。

安装完成后，服务将自动运行在 http://localhost:5000

查询版本

使用版本查询脚本快速查看安装状态和版本信息：


./version.sh

该脚本会显示：

已安装的版本号
安装路径
服务运行状态
API版本信息（如果服务正在运行）

方式二：手动安装

如果您希望手动配置，请按以下步骤操作：

1. 安装系统依赖


# Ubuntu/Debian
sudo apt install flatpak python3 python3-pip

# Fedora
sudo dnf install flatpak python3 python3-pip

# Arch Linux
sudo pacman -S flatpak python python-pip

2. 安装 Python 依赖


pip install flask flask-cors

3. 手动启动服务器


python3 FlatpakAPI.py

服务器将在 http://0.0.0.0:5000 上运行。

卸载

如果使用安装脚本安装，可以使用卸载脚本：


sudo ./uninstall.sh

卸载脚本会：

停止运行中的服务
禁用开机自启动
删除 systemd 服务文件

注意：Python依赖包不会被自动删除，如需删除请手动运行：


pip3 uninstall flask flask-cors

服务管理

如果使用安装脚本安装，服务将通过 systemd 管理，可使用以下命令：


# 查看服务状态
sudo systemctl status flatpak-localserver

# 启动服务
sudo systemctl start flatpak-localserver

# 停止服务
sudo systemctl stop flatpak-localserver

# 重启服务
sudo systemctl restart flatpak-localserver

# 查看实时日志
sudo journalctl -u flatpak-localserver -f

# 禁用开机自启动
sudo systemctl disable flatpak-localserver

# 启用开机自启动
sudo systemctl enable flatpak-localserver

使用方法

方式一：通过 systemd 服务（推荐）

如果您使用 install.sh 安装，服务已自动启动并设置开机自启动，无需手动操作。

验证服务状态：


# 查看服务状态
sudo systemctl status flatpak-localserver

# 测试 API 是否正常响应
curl http://localhost:5000/health

方式二：手动启动（开发模式）

如果您是开发者或想要手动运行：


# 直接运行脚本
python3 FlatpakAPI.py

# 或者从安装目录运行（如果已安装）
cd /opt/.FlatpakCN
python3 FlatpakAPI.py

服务器将在 http://0.0.0.0:5000 上运行。

实用工具脚本

项目提供了多个实用脚本帮助您管理和测试：

1. 版本查询脚本


./version.sh

显示安装版本、路径、服务状态等信息。

2. 系统信息测试脚本


./test_version.sh

显示详细的系统信息并测试 /api/version 端点，用于诊断和验证环境。

3. 安装脚本


sudo ./install.sh

一键安装并配置服务。

4. 卸载脚本


sudo ./uninstall.sh

完整卸载服务和文件。

常见使用场景

场景1：安装一个应用


# 使用 curl 通过 API 安装应用
curl -X POST http://localhost:5000/api/flatpak/install \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org.gimp.GIMP",
    "remote": "flathub"
  }'

# 获取任务ID后，查询安装进度
curl http://localhost:5000/api/tasks

场景2：查看已安装的应用


curl http://localhost:5000/api/flatpak/list | python3 -m json.tool

场景3：搜索应用


curl "http://localhost:5000/api/flatpak/search?query=firefox" | python3 -m json.tool

场景4：更新所有应用


curl -X POST http://localhost:5000/api/flatpak/update \
  -H "Content-Type: application/json"

场景5：卸载应用


curl -X POST http://localhost:5000/api/flatpak/uninstall \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org.gimp.GIMP"
  }'

场景6：监控任务执行


# 使用 watch 命令实时监控任务状态
watch -n 1 "curl -s http://localhost:5000/api/tasks | python3 -m json.tool"

场景7：查看系统和环境信息


# 获取完整的系统环境信息
curl http://localhost:5000/api/version | python3 -m json.tool

快速验证安装

安装完成后，可以快速测试服务是否正常：


# 1. 检查服务状态
sudo systemctl status flatpak-localserver

# 2. 健康检查
curl http://localhost:5000/health

# 3. 版本信息
curl http://localhost:5000/api/version

# 4. 列出已安装应用
curl http://localhost:5000/api/flatpak/list

# 或使用版本查询脚本
./version.sh

API 端点

健康检查


GET /health

响应示例：


{
  "status": "healthy",
  "message": "Flatpak API service is running",
  "version": "1.0.0"
}

版本信息


GET /api/version

获取 API 版本和完整的系统环境信息。

响应示例：


{
  "api_version": "1.0.0",
  "author": "FlatpakCN",
  "description": "Flatpak LocalServer API - A RESTful API for managing Flatpak applications",
  "python": {
    "version": "3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0]",
    "version_info": "3.10.12",
    "executable": "/usr/bin/python3"
  },
  "system": {
    "os": "Linux",
    "os_release": "6.5.0-35-generic",
    "os_version": "#35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC",
    "machine": "x86_64",
    "processor": "x86_64",
    "platform": "Linux-6.5.0-35-generic-x86_64-with-glibc2.35"
  },
  "distribution": {
    "id": "ubuntu",
    "name": "Ubuntu",
    "version": "22.04",
    "pretty_name": "Ubuntu 22.04.3 LTS"
  },
  "flatpak_version": "Flatpak 1.12.7",
  "desktop_environment": "gnome",
  "display_server": "wayland",
  "hostname": "mycomputer"
}

应用管理

列出已安装的应用


GET /api/flatpak/list

安装应用


POST /api/flatpak/install
Content-Type: application/json

{
  "name": "org.gimp.GIMP",
  "remote": "flathub",
  "branch": "stable"  // 可选
}

卸载应用


POST /api/flatpak/uninstall
Content-Type: application/json

{
  "name": "org.gimp.GIMP",
  "branch": "stable"  // 可选
}

更新应用


POST /api/flatpak/update
Content-Type: application/json

{
  "name": "org.gimp.GIMP",  // 可选，不提供则更新所有应用
  "branch": "stable"        // 可选
}

运行应用


POST /api/flatpak/run
Content-Type: application/json

{
  "name": "org.gimp.GIMP",
  "args": ["--help"]  // 可选
}

搜索应用


GET /api/flatpak/search?query=gimp

获取应用信息


GET /api/flatpak/info?id=org.gimp.GIMP

远程仓库管理

列出远程仓库


GET /api/flatpak/remote/list

添加远程仓库


POST /api/flatpak/remote/add
Content-Type: application/json

{
  "name": "flathub",
  "url": "https://dl.flathub.org/repo/flathub.flatpakrepo"
}

删除远程仓库


POST /api/flatpak/remote/remove
Content-Type: application/json

{
  "name": "flathub"
}

任务管理

获取所有任务


GET /api/tasks

响应示例：


{
  "tasks": [
    {
      "id": "task-uuid",
      "type": "install",
      "name": "org.gimp.GIMP",
      "status": "running",
      "created_at": "2024-01-01T12:00:00",
      "start_time": "2024-01-01T12:00:01",
      "logs": ["正在安装...", "下载中..."],
      "meta": {}
    }
  ],
  "current_task": "task-uuid"
}

取消任务


POST /api/tasks/cancel/{task_id}

清除已完成的任务


POST /api/tasks/clear

任务状态

任务可能处于以下状态之一：

pending - 等待处理
running - 正在执行
success - 执行成功
failed - 执行失败
cancelled - 已取消

工作原理

任务队列系统

任务提交：客户端通过 API 提交任务（如安装应用）
任务入队：任务被添加到队列并分配唯一 ID
后台处理：工作线程从队列中取出任务并执行
状态更新：任务状态实时更新，客户端可查询进度
日志记录：命令输出实时记录到任务日志中

线程安全

使用 threading.Lock 确保任务状态的读写操作是线程安全的，防止并发访问导致的数据不一致。

示例使用场景

使用 curl 安装应用


# 安装 GIMP
curl -X POST http://localhost:5000/api/flatpak/install \
  -H "Content-Type: application/json" \
  -d '{"name": "org.gimp.GIMP", "remote": "flathub"}'

# 获取任务状态
curl http://localhost:5000/api/tasks

使用 JavaScript 前端


// 安装应用
async function installApp(appId) {
  const response = await fetch('http://localhost:5000/api/flatpak/install', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: appId, remote: 'flathub' })
  });
  const result = await response.json();
  console.log('任务 ID:', result.task_id);
  
  // 轮询任务状态
  const taskId = result.task_id;
  const interval = setInterval(async () => {
    const taskResponse = await fetch('http://localhost:5000/api/tasks');
    const tasks = await taskResponse.json();
    const task = tasks.tasks.find(t => t.id === taskId);
    
    if (task.status === 'success') {
      console.log('安装成功！');
      clearInterval(interval);
    } else if (task.status === 'failed') {
      console.log('安装失败:', task.result?.error);
      clearInterval(interval);
    }
  }, 1000);
}

配置

修改服务器端口

编辑 FlatpakAPI.py 文件的最后一行：


app.run(host='0.0.0.0', port=5000, debug=True)

将 port=5000 改为您需要的端口号。

生产环境部署

⚠️ 警告：当前代码使用 Flask 的开发服务器（debug=True），不适合生产环境。

生产环境建议使用 Gunicorn 或 uWSGI：


# 安装 Gunicorn
pip install gunicorn

# 运行生产服务器
gunicorn -w 4 -b 0.0.0.0:5000 FlatpakAPI:app

安全注意事项

权限管理：Flatpak 操作可能需要管理员权限
访问控制：默认允许所有跨域请求，生产环境应限制 CORS
输入验证：当前实现了基本的输入验证，建议增强
命令注入：应用名称直接用于命令行，确保来源可信

故障排除

常见问题

问题：服务器启动失败

确保端口 5000 未被占用
检查 Python 版本是否 3.6+

问题：Flatpak 命令失败

确保系统已安装 Flatpak
检查 Flatpak 远程仓库是否配置正确
运行 flatpak --version 验证安装

问题：任务一直处于 pending 状态

检查工作线程是否正常运行
查看服务器日志是否有错误信息

架构设计


客户端请求 → Flask 路由 → 创建任务 → 任务队列
                                          ↓
                                     工作线程
                                          ↓
                                    执行 Flatpak 命令
                                          ↓
                                    更新任务状态
                                          ↓
                              客户端轮询获取状态

更新日志

v1.0.0

初始版本
支持基本的 Flatpak 操作
实现任务队列管理
添加任务取消功能

35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen

京ICP备11018762号-111