LoongApps Agent

1.项目简介

LoongApps Agent 是专为龙芯应用合作社设计的本地代理组件，它允许网站通过自定义协议 loongapps:// 和本地 HTTP API 与系统的软件包管理系统进行安全交互。

该代理组件架起了 Web 应用与本地系统之间的桥梁，使用户能够在浏览器中直接安装软件包，无需离开网页环境。

1.1.核心价值

• 无缝体验：用户在网页中即可完成软件安装，无需打开终端
• 安全保障：使用 PolicyKit 权限验证，避免密码明文存储
• 资源高效：Systemd socket 激活机制，按需启动，节省系统资源
• 跨浏览器支持：兼容主流浏览器，提供配置引导

---

2.功能特性

2.1.自定义协议支持

• 处理 loongapps://install?pkg=xxx 协议调用
• 自动启动图形化安装界面
• 支持安装和卸载操作

2.2.HTTP API 服务

• 提供系统信息查询接口（操作系统、架构、版本等）
• 仅监听本地回环地址，确保安全

2.3.图形化安装界面

• 使用 Qt6 (PySide6) 构建现代化 UI
• 实时显示安装进度和输出信息
• 集成 PolicyKit 权限验证

2.4.Systemd 集成

• Socket 激活机制，无请求时不运行
• 自动管理服务生命周期
• 完整的安全加固配置

2.5.Debian 打包

• 标准 deb 包格式
• 完整的依赖管理
• 自动化构建脚本

2.6.安全特性

• PolicyKit 权限验证
• 严格的输入验证和包名校验
• 防止命令注入攻击
• Systemd 安全限制（NoNewPrivileges、ProtectSystem 等）

---

3.系统架构

3.1.整体架构图

网站 (Web Browser)
    ↓
1. loongapps://install?pkg=xxx
    ↓
2. 本地协议处理器 (.desktop)
    ↓
3. loongapps-agent (主程序)
    ├─→ ui-installer.py (图形化安装)
    │      ↓
    │   sudo apt install
    │
    └─→ HTTP API (127.0.0.1:54123)
           └─ /system/info

3.2.核心组件说明

组件	文件	功能说明
主程序	src/loongapps-agent.py	处理协议调用和 HTTP 请求的路由
API 模块	src/api.py	提供系统信息和包状态查询功能
UI 安装器	src/ui-installer.py	Qt6 图形化安装界面
Socket 配置	systemd/loongapps-agent.socket	Systemd socket 激活配置
服务配置	systemd/loongapps-agent@.service	Systemd 服务实例配置
桌面集成	desktop/loongapps.desktop	自定义协议处理器注册

---

4.快速开始

4.1.系统要求

• 操作系统：Loongnix 或其他基于 Debian 的 LoongArch64 系统
• Python 版本：Python 3.6 或更高版本
• 系统依赖：
  • systemd (系统自带)
  • apt/dpkg (系统自带)
  • python3-pyside6 (打包时自动安装)
  • policykit-1 (系统自带)

4.2.安装方法

方法 1：从 deb 包安装（推荐）

# 安装构建工具
sudo apt update
sudo apt install build-essential debhelper devscripts dpkg-dev fakeroot

# 构建包
./build.sh

# 安装
sudo dpkg -i ../loongapps-agent_1.0.0_loong64.deb

# 如果有依赖问题
sudo apt-get install -f

方法 2：从源码运行（开发模式）

# 安装依赖
sudo apt install python3-pyside6 libpyside6-py3-6.8, python3-pyside6.qtwidgets, python3-pyside6.qtsvg

# 运行主程序
python3 src/loongapps-agent.py

4.3.验证安装

# 1. 检查服务状态
sudo systemctl status loongapps-agent.socket

# 2. 测试 API
curl http://127.0.0.1:54123/system/info

# 3. 测试协议调用（在浏览器地址栏输入）
loongapps://install?pkg=vlc

4.4.预期输出

API 测试输出示例：

{
  "os": "Linux",
  "release": "6.6.0-loongson-3",
  "arch": "loongarch64",
  "platform": "Linux-6.6.0-loongson-3-loongarch64-with-glibc2.38"
}

---

5.使用指南

5.1.浏览器兼容性

本项目支持多种浏览器，但不同浏览器对自定义协议的处理方式不同：

浏览器	兼容性	需要额外配置
LBrowser/Chrome/Chromium	✅ 完全支持	否
Firefox	✅ 完全支持	否

5.2.协议格式

支持的协议格式：

协议	功能	示例
loongapps://install?pkg=xxx	安装软件包	loongapps://install?pkg=vlc

5.3.包名验证规则

包名必须符合以下正则表达式：

[a-z0-9][a-z0-9+.-]*[a-z0-9]

有效包名示例：

• vlc
• python3-pip
• libssl-dev
• firefox-esr

无效包名示例：

• VLC（大写字母）
• python 3（包含空格）
• ../malicious（包含路径遍历）
• pkg!name（包含非法字符）

---

6.API 说明

6.1.基础信息

• Base URL: http://127.0.0.1:54123
• 协议: HTTP/1.1
• 数据格式: JSON
• 字符编码: UTF-8

6.2.获取系统信息

请求

GET /system/info HTTP/1.1
Host: 127.0.0.1:54123

响应示例

{
  "os": "Linux",
  "release": "6.6.52-loong64",
  "arch": "loongarch64",
  "platform": "Linux-6.6.0-loongson-3-loongarch64-with-glibc2.38"
}

响应字段说明

字段	类型	说明
os	string	操作系统名称
release	string	内核版本
arch	string	系统架构
platform	string	完整平台信息

6.3.安全限制

• 仅允许 GET 请求
• 仅允许访问 /system/info 和 /system/package/ 路径
• 所有其他路径返回 404 错误
• HTTP 请求大小限制为 8KB

---

7.服务管理

7.1.查看服务状态

sudo systemctl status loongapps-agent.socket

预期输出：

● loongapps-agent.socket - LoongApps Local Agent Socket
     Loaded: loaded (/etc/systemd/system/loongapps-agent.socket; enabled; vendor preset: enabled)
     Active: active (listening) since Mon 2024-01-23 10:00:00 CST; 1h ago
   Listen: 127.0.0.1:54123 (Stream)
     CGroup: /system.slice/loongapps-agent.socket

7.2.启动/停止服务

# 启动服务
sudo systemctl start loongapps-agent.socket

# 停止服务
sudo systemctl stop loongapps-agent.socket

# 重启服务
sudo systemctl restart loongapps-agent.socket

7.3.开机自启

# 启用开机自启
sudo systemctl enable loongapps-agent.socket

# 禁用开机自启
sudo systemctl disable loongapps-agent.socket

7.4.查看日志

# 查看 socket 激活日志
sudo journalctl -u loongapps-agent.socket -f

# 查看服务实例日志
sudo journalctl -u loongapps-agent@* -f

# 查看最近 50 条日志
sudo journalctl -u loongapps-agent@* -n 50

# 查看特定时间的日志
sudo journalctl -u loongapps-agent@* --since "10 minutes ago"

---

8.安全特性

8.1.Systemd 安全加固

服务配置包含以下安全措施：

配置项	值	说明
NoNewPrivileges	yes	禁止进程获取新权限
PrivateTmp	yes	使用独立的 /tmp 目录
ProtectSystem	strict	严格保护系统目录为只读
ProtectHome	yes	隔离用户主目录
RestrictSUIDSGID	yes	限制 SUID/SGID 程序
LockPersonality	yes	锁定 personality

8.2.资源限制

• 任务限制: TasksMax=16 - 最多 16 个任务
• 内存限制: MemoryMax=100M - 内存限制 100MB
• CPU 限制: CPUQuota=50% - CPU 使用限制 50%
• 最大连接数: MaxConnections=16 - Socket 最大连接数

8.3.网络安全

• HTTP API 仅监听 127.0.0.1:54123，不接受外部连接
• Socket 激活机制，无请求时不运行服务
• 仅允许 GET 请求，禁用 POST/PUT/DELETE
• 严格的路径白名单验证

8.4.权限验证

• 使用 pkexec (PolicyKit) 进行权限提升
• 避免密码明文存储
• 每次操作都需要用户授权

8.5.输入验证

• 包名严格正则验证：[a-z0-9][a-z0-9+.-]*[a-z0-9]
• 防止路径遍历攻击（.., /, .）
• HTTP 请求大小限制为 8KB
• 命令注入防护（使用 shlex.quote）

---

8.6.构建和打包

快速构建：

# 构建包
./build.sh

# 安装
sudo dpkg -i ../loongapps-agent_1.0.0_loong64.deb

8.7.测试指南

8.7.1.集成测试

# 测试协议调用
python3 src/loongapps-agent.py "loongapps://install?pkg=hello"

# 测试 API
curl http://127.0.0.1:54123/system/info

# 测试服务
sudo systemctl restart loongapps-agent.socket
sudo systemctl status loongapps-agent.socket

---