一个跨平台的桌面服务,通过 RESTful HTTP API 管理多个进程。此服务提供全面的进程管理功能,包括内置监控、日志记录和配置持久化。
- 跨平台支持:Windows、Linux 和 macOS
- RESTful HTTP API:通过 HTTP 端点完整的进程管理
- 进程监控:实时状态跟踪、PID 监控和重启计数
- 自动启动支持:服务启动时自动启动配置的进程
- 权限提升:需要时以管理员/root 权限运行进程
- 配置持久化:进程配置自动保存和恢复
- 集中日志记录:每个受管进程的独立日志文件,支持轮转
- API 认证:简单而有效的 API 密钥认证
- 服务集成:原生支持 Windows 服务、systemd 和 launchd
服务由几个关键组件组成:
- HTTP API 服务器 - 提供进程管理的 RESTful 端点
- 核心进程管理器 - 处理进程生命周期、监控和配置
- 跨平台服务层 - 与特定操作系统的服务管理集成
- 配置系统 - 进程配置和设置的持久化存储
从仓库下载最新版本并运行安装程序:
# 以管理员身份运行
.\install-openlist-service.exe
# 使用 sudo 权限运行
sudo ./install-openlist-service
# 使用管理员权限运行
sudo ./install-openlist-service
- Rust 1.70+ 和 Cargo
- 平台特定依赖:
- Windows:Visual Studio Build Tools 或 Visual Studio
- Linux:
build-essential
、pkg-config
、libssl-dev
- macOS:Xcode 命令行工具
# 克隆仓库
git clone https://github.com/OpenListTeam/openlist-desktop-service.git
cd openlist-desktop-service
# 构建发布版本
cargo build --release
# 安装服务
sudo ./target/release/install-openlist-service
可以使用以下环境变量配置服务:
变量 | 默认值 | 描述 |
---|---|---|
PROCESS_MANAGER_HOST |
127.0.0.1 |
API 服务器绑定地址 |
PROCESS_MANAGER_PORT |
53211 |
API 服务器端口 |
PROCESS_MANAGER_API_KEY |
(内置) | API 认证密钥 |
$env:PROCESS_MANAGER_API_KEY="your-secure-api-key"
$env:PROCESS_MANAGER_PORT="8080"
set PROCESS_MANAGER_API_KEY=your-secure-api-key
set PROCESS_MANAGER_PORT=8080
export PROCESS_MANAGER_API_KEY="your-secure-api-key"
export PROCESS_MANAGER_PORT="8080"
服务在安装后会自动启动。您也可以手动控制:
# 启动服务
Start-Service -Name "openlist_desktop_service"
# 停止服务
Stop-Service -Name "openlist_desktop_service"
# 检查状态
Get-Service -Name "openlist_desktop_service"
# 启动服务
sudo systemctl start openlist-desktop-service
# 停止服务
sudo systemctl stop openlist-desktop-service
# 检查状态
sudo systemctl status openlist-desktop-service
# 启动服务
sudo launchctl start io.github.openlistteam.openlist.service
# 停止服务
sudo launchctl stop io.github.openlistteam.openlist.service
服务运行后,您可以通过 HTTP API 与其交互:
# 检查(无需认证)
curl http://127.0.0.1:53211/health
# 列出所有进程
curl -H "Authorization: your-api-key" http://127.0.0.1:53211/api/v1/processes
# 获取服务版本
curl -H "Authorization: your-api-key" http://127.0.0.1:53211/api/v1/version
所有受保护的端点都需要在 Authorization
头中提供 API 密钥:
Authorization: your-api-key
# 或
Authorization: Bearer your-api-key
方法 | 端点 | 描述 |
---|---|---|
GET | /health |
检查(无需认证) |
GET | /api/v1/status |
获取服务状态 |
GET | /api/v1/version |
获取版本信息 |
POST | /api/v1/service/stop |
停止整个服务 |
GET | /api/v1/processes |
列出所有进程 |
POST | /api/v1/processes |
创建新进程 |
GET | /api/v1/processes/:id |
获取进程详情 |
PUT | /api/v1/processes/:id |
更新进程配置 |
DELETE | /api/v1/processes/:id |
删除进程 |
POST | /api/v1/processes/:id/start |
启动进程 |
POST | /api/v1/processes/:id/stop |
停止进程 |
GET | /api/v1/processes/:id/logs |
获取进程日志 |
curl -X POST -H "Authorization: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "我的应用程序",
"bin_path": "/path/to/executable",
"args": ["--port", "8080", "--verbose"],
"log_file": "/path/to/app.log",
"working_dir": "/path/to/workdir",
"auto_restart": false,
"auto_start": true,
"run_as_admin": false
}' \
http://127.0.0.1:53211/api/v1/processes
curl -X POST -H "Authorization: your-api-key" \
http://127.0.0.1:53211/api/v1/processes/{process-id}/start
curl -H "Authorization: your-api-key" \
"http://127.0.0.1:53211/api/v1/processes/{process-id}/logs?lines=50"
curl -X POST -H "Authorization: your-api-key" \
http://127.0.0.1:53211/api/v1/service/stop
所有 API 响应都遵循这个标准格式:
{
"success": true,
"data": { ... },
"error": null,
"timestamp": 1640995200
}
创建或更新进程时,您可以指定:
name
:进程的显示名称bin_path
:可执行二进制文件的路径args
:命令行参数数组(可选)log_file
:日志文件路径(可选,如果未提供会自动生成)working_dir
:进程的工作目录(可选)env_vars
:环境变量键值对(可选)auto_restart
:是否在失败时自动重启(可选)auto_start
:服务启动时是否自动启动(可选)run_as_admin
:是否以管理员/root 权限运行(可选)
- 在生产环境中更改默认 API 密钥
- 使用环境变量安全地设置 API 密钥
- 在生产环境中考虑使用反向代理配置 HTTPS
run_as_admin
功能需要服务以足够的权限运行- 在 Windows 上,除非服务以管理员身份运行,否则可能出现 UAC 提示
- 在 Linux/macOS 上,服务用户必须具有 sudo 权限才能无缝操作
- 谨慎使用权限提升,仅在必要时使用
- 服务日志存储在配置文件旁边
- 单个进程日志存储在进程创建时指定的位置
- 日志轮转自动处理(最大 10MB,保留 3 个文件)
- 检查服务日志中的错误消息
- 验证端口 53211 未被其他应用程序占用
- 确保配置目录具有适当的权限
- 在 Linux/macOS 上,检查 systemd/launchd 日志
- 验证二进制文件路径存在且可执行
- 检查工作目录是否存在
- 查看进程日志了解具体错误消息
- 确保目标二进制文件具有适当的权限
- 验证 API 密钥设置正确
- 检查 Authorization 头格式
- 确保服务正在运行且可访问
要移除服务:
# 以管理员身份运行
.\uninstall-openlist-service.exe
# 使用 sudo 权限运行
sudo ./uninstall-openlist-service
# 使用管理员权限运行
sudo ./uninstall-openlist-service
这将停止所有受管进程,移除服务注册,并清理配置文件。
- Fork 仓库
- 创建功能分支
- 进行更改
- 如适用,添加测试
- 提交拉取请求
此项目采用 GPL-3.0 许可证 - 详情请参见 LICENSE 文件。
如有问题、疑问或贡献,请访问 GitHub 仓库。