Skip to content
wanghuawangyu
ggufy-web
Public

About

轻量级、自包含的 Rust 二进制程序，统一管理 llama.cpp、Ollama 及其他 GGUF 兼容工具的模型文件。

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

ggufy-web

GGUF 模型别名管理的 Web 界面
轻量级、自包含的 Rust 二进制程序，统一管理 llama.cpp、Ollama 及其他 GGUF 兼容工具的模型文件。

功能特性

  • 🔍 自动发现模型 — 扫描多个目录（包括 Ollama 的哈希命名 blobs），自动识别所有 GGUF 文件。
  • 📋 元数据提取 — 从 GGUF 文件头读取模型架构（general.architecture）、文件大小和名称。
  • 🔗 软链接管理 — 通过 Web 界面为模型创建、更新、删除人类可读的别名（软链接）。
  • 🌐 REST API — 完整的 JSON API，支持程序化访问和集成。
  • 🖥️ 内嵌 Web 界面 — 单页应用直接编译进二进制，无需外部前端依赖。
  • 📦 单二进制分发 — 静态编译，无任何运行时依赖（无需 Python、JVM 等）。
  • ⚡ 快速轻量 — 基于 Rust + Axum + Tokio 构建，高性能低内存占用。
image

系统架构

┌─────────────────────────────────────────────────────┐
│                    ggufy-web                        │
│  ┌─────────────┐  ┌─────────────┐  ┌───────────┐   │
│  │   Web UI    │  │  REST API   │  │  核心逻辑  │   │
│  │ (HTML/JS)   │◄─┤ (axum)      │  │ - 扫描    │   │
│  │             │  │             │  │ - 元数据  │   │
│  └─────────────┘  └─────────────┘  │ - 软链接  │   │
│         │               │          └───────────┘   │
└─────────┼───────────────┼──────────────────────────┘
          │               │
          ▼               ▼
┌─────────────────────────────────────────────┐
│                  文件系统                     │
│  ┌─────────────────┐  ┌─────────────────┐   │
│  │ Ollama blobs/   │  │ 自定义目录      │   │
│  │ (哈希文件名)    │  │ (.gguf 文件)    │   │
│  └─────────────────┘  └─────────────────┘   │
│                    │                         │
│                    ▼                         │
│         ┌───────────────────┐                │
│         │  软链接目录       │                │
│         │  ~/.ggufy/models/ │                │
│         │  - llama3.1.gguf  │                │
│         │  - qwen2.5.gguf   │                │
│         └───────────────────┘                │
└─────────────────────────────────────────────┘

命令行使用

ggufy-web [选项]

参数说明

参数 短选项 长选项 默认值 说明
--config -c --config ~/.ggufy-web/config.ini INI 配置文件路径
--port -p --port 8090 监听端口
--host -H --host 0.0.0.0 监听 IP 地址
--scan-dirs -s --scan-dirs ~/.ollama/models/blobs, . 逗号分隔的要扫描的目录列表
--link-dir -l --link-dir ~/.ggufy/models 软链接别名存放目录
--log --log 无（输出到控制台） 日志文件路径，指定后日志写入文件并自动绕接
--log-level --log-level info 日志级别：trace、debug、info、warn、error

配置优先级

所有配置项的最终值按以下优先级决定（高 → 低）：

  1. 命令行参数 — 显式传入的参数优先级最高
  2. INI 配置文件 — 通过 --config 指定，或默认为 ~/.ggufy-web/config.ini
  3. 程序内部默认值 — 当命令行和配置文件均未指定时使用的默认值

config.ini 配置样例

创建一个 INI 配置文件（例如 ~/.ggufy-web/config.ini），将所有参数写入 [general] 节：

[general]
; 监听端口
port = 8090

; 监听 IP 地址
host = 0.0.0.0

; 逗号分隔的扫描目录列表
scan_dirs = /home/user/models, /home/user/.ollama/models/blobs

; 软链接存放目录
link_dir = /home/user/.ggufy/models

; 日志文件路径（不设置则输出到控制台）
log = /var/log/ggufy-web.log

; 日志级别: trace, debug, info, warn, error
log_level = info

启动时自动加载默认路径的配置文件：

# 自动加载 ~/.ggufy-web/config.ini（若存在）
ggufy-web

使用自定义路径的配置文件：

ggufy-web --config /etc/ggufy-web/config.ini

命令行参数可覆盖配置文件中的对应项：

# 使用配置文件中的其他设置，仅覆盖端口和日志级别
ggufy-web --config ~/.ggufy-web/config.ini --port 9000 --log-level debug

使用示例

使用默认配置启动（扫描当前目录 + Ollama blobs，链接目录为 ~/.ggufy/models）：

ggufy-web

自定义端口和扫描目录：

ggufy-web --port 8090 --scan-dirs /data/models,/mnt/ollama/blobs

指定监听 IP 和端口：

ggufy-web --host 127.0.0.1 --port 8090

输出日志到文件（自动绕接，单文件最大 20MB，历史日志压缩为 zip）：

ggufy-web --log /var/log/ggufy-web.log

指定日志级别并输出到文件：

ggufy-web --log ./ggufy-web.log --log-level debug

完整指定所有参数：

ggufy-web -p 8080 -H 0.0.0.0 -s ~/models,~/ollama_blobs -l ~/my_aliases --log ./app.log --log-level warn

REST API

方法 端点 说明
GET /api/models 列出所有已发现的模型及其元数据和别名状态
POST /api/links 为模型创建软链接别名
PUT /api/links/:alias 更新已有别名的目标文件
DELETE /api/links/:alias 删除软链接别名（不会删除源文件）
GET /api/links 列出所有当前软链接
POST /api/config/scan_dirs 更新扫描目录（持久化到磁盘）
POST /api/reload 重新扫描所有目录

所有响应遵循统一 JSON 格式：

{
  "success": true,
  "data": { ... },
  "error": null
}

示例：创建软链接

curl -X POST http://localhost:8090/api/links \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/path/to/model.gguf", "alias": "my-llama"}'

示例：列出模型

curl http://localhost:8090/api/models

最佳实践

🏷️ 别名命名

  • 使用简短、描述性强的名称（如 llama3.1-8b、qwen2.5-7b）。
  • 避免空格和特殊字符，建议使用 [a-zA-Z0-9_-]。
  • 别名即为软链接文件名（自动添加 .gguf 后缀）。

📁 目录配置

  • ggufy-web 可放在任意位置运行，单二进制无依赖。
  • 建议将软链接目录放在稳定位置（默认 ~/.ggufy/models）。
  • 将 llama.cpp / Ollama 指向软链接目录： 
    # llama.cpp
llama-cli -m ~/.ggufy/models/llama3.1-8b.gguf

# Ollama 通过 Modelfile
FROM ~/.ggufy/models/llama3.1-8b.gguf

🛡️ 持久化配置

通过 Web 界面或 API 更新扫描目录后，配置会自动保存到 ~/.config/ggufy-web/config.json。下次启动时，持久化配置会优先于默认值加载。

从源码构建

前置条件

  • Rust（Edition 2021，最低版本 1.75+）
  • 对应平台的构建工具（gcc/clang、MSVC 等）

开发构建

cargo build

发布构建（优化、去除符号）

cargo build --release

静态链接分发

Linux (musl)：

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Windows (静态 CRT)：

RUSTFLAGS="-C target-feature=+crt-static" cargo build --release

macOS：

RUSTFLAGS="-C target-feature=+crt-static" cargo build --release

项目结构

ggufy-web/
├── Cargo.toml
├── templates/
│   └── index.html              # Web 界面的 Askama 模板
├── src/
│   ├── main.rs                 # 入口点、CLI 解析、服务器启动
│   ├── config.rs               # 配置（扫描目录、链接目录、端口）
│   ├── error.rs                # AppError 类型及 HTTP 响应转换
│   ├── model/
│   │   ├── mod.rs
│   │   ├── metadata.rs         # GGUF 元数据提取
│   │   └── registry.rs         # 模型注册表（扫描、查询、缓存）
│   ├── link/
│   │   ├── mod.rs
│   │   ├── manager.rs          # 软链接增删改查操作
│   │   └── resolver.rs         # 路径解析与冲突检测
│   ├── api/
│   │   ├── mod.rs              # 路由设置、AppState
│   │   ├── handlers.rs         # 请求处理函数
│   │   └── response.rs         # 统一 JSON 响应格式
│   ├── web/
│   │   └── mod.rs              # Web UI 处理（Askama 模板渲染）
│   └── utils/
│       ├── mod.rs
│       └── fs.rs               # 文件系统辅助函数

与其他工具对比

工具 范围 界面 运行时依赖
ggufy-web 磁盘级模型别名管理 Web UI 无（静态二进制）
ggufy (CLI) 磁盘级模型别名管理 命令行 无
llamaMan llama.cpp 运行时管理 图形界面 Python
Ollama Web UI Ollama 运行时与模型管理 Web UI Python / Node.js

ggufy-web 专注于 文件组织 —— 让模型文件可发现且命名一致，运行时管理交由专业工具处理。

许可证

MIT OR Apache-2.0

About

轻量级、自包含的 Rust 二进制程序，统一管理 llama.cpp、Ollama 及其他 GGUF 兼容工具的模型文件。

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages