Stable-Diffusion.cpp WebUI [Beta]

⚠️ Beta Version Notice

This is an early preview release (v0.1.0-beta) with the following limitations:

• Tested only on macOS Apple Silicon (M1/M2/M3)
• Some features may be unstable or contain bugs
• Windows/Linux support not yet available
• API may change in future versions

Feedback and contributions are welcome!

基于 stable-diffusion.cpp 的现代化 Web 管理界面，为 macOS (Apple Silicon) 优化。

功能特性

• 🎨 文生图 (txt2img) - 根据文本提示词生成图片
• 🖼️ 图生图 (img2img) - 基于输入图片生成变体
• ✏️ 图像修复 (inpaint) - 局部重绘和修复
• 🔍 超分辨率 (upscale) - 图片放大增强
• 📦 模型管理 - 扫描、加载、切换模型
• 📚 历史记录 - 浏览、搜索、收藏生成历史
• ⚙️ 预设管理 - 风格模板和自定义预设
• 📊 资源监控 - CPU/内存/GPU 实时状态
• 🖥️ 桌面应用 - Tauri 打包的原生 macOS 应用

技术栈

前端: React 19 + TypeScript + Zustand + Tailwind CSS 4 + Vite 8
后端: Bun + Hono + SQLite (Drizzle ORM)
桌面: Tauri 2.x (Rust)
引擎: stable-diffusion.cpp v1.8.0+ (Metal 加速)

快速开始

Environment Requirements

• macOS 13.0+ (Ventura or later, recommended)
• macOS 12.0+ (Monterey, minimum support)
• Apple Silicon Mac (M1/M2/M3) - Required
• 16GB RAM (recommended) / 8GB RAM (minimum)
• Bun 1.0+
• Rust 1.70+ (for Tauri build)
• Xcode Command Line Tools
• stable-diffusion.cpp v1.8.0+ (installed separately)

安装

# 克隆项目
git clone <repository-url>
cd sd-webui

# 安装依赖
bun install

# 运行环境检查
bun run setup

开发模式

# 启动开发服务器 (前后端同时启动)
bun run dev

# 或分别启动
bun run dev:frontend    # http://localhost:5173
bun run dev:server      # http://localhost:7860

生产构建

# 构建所有项目
bun run build

# 分别构建
bun run build:frontend
bun run build:server

项目结构

sd-webui/
├── frontend/           # 前端项目 (React + TypeScript)
│   ├── src/
│   │   ├── features/   # 功能模块
│   │   ├── shared/     # 共享组件
│   │   ├── services/   # API 服务
│   │   └── styles/     # 样式
│   └── package.json
│
├── server/             # 后端项目 (Bun + Hono)
│   ├── src/
│   │   ├── routes/     # 路由
│   │   ├── services/   # 业务逻辑
│   │   ├── engine/     # 引擎交互
│   │   └── db/         # 数据库
│   └── package.json
│
├── src-tauri/          # Tauri 桌面应用 (Rust)
│   ├── src/
│   │   └── main.rs     # Tauri 主入口
│   ├── icons/          # 应用图标
│   ├── Cargo.toml      # Rust 依赖配置
│   └── tauri.conf.json # Tauri 配置
│
├── shared/             # 共享类型定义
├── scripts/            # 开发脚本
├── docs/               # 文档
├── e2e/                # E2E 测试 (Playwright)
└── package.json        # Workspace 配置

开发指南

代码规范

• TypeScript 严格模式
• ESLint + Prettier 自动格式化
• Conventional Commits 提交规范

# 代码检查
bun run lint

# 代码格式化
bun run format

# 类型检查
bun run typecheck

# 运行测试
bun run test

Git Hooks

项目使用 Husky 自动化代码检查:

• pre-commit: 运行 lint-staged
• commit-msg: 验证提交信息格式

文档

• 架构设计文档
• 开发任务清单
• 项目开发规范

⚠️ Known Issues

Beta Version Limitations

1. Platform Limitation: Only supports macOS Apple Silicon. Windows/Linux support is planned.
2. Model Compatibility: Only tested with select GGUF models. Some models may not work properly.
3. Memory Usage: Large model generation may consume significant memory. 16GB+ RAM recommended.
4. Initial Startup: First model load takes 30-60 seconds. Subsequent loads are faster.
5. DMG Signing: Not notarized by Apple. First launch requires manual confirmation.

See RELEASE_NOTES_BETA.md for detailed information.

❓ FAQ

Q: stable-diffusion.cpp 如何安装？

参考官方仓库：https://github.com/leejet/stable-diffusion.cpp

# macOS (Homebrew)
brew install stable-diffusion.cpp

# 或从源码编译
git clone https://github.com/leejet/stable-diffusion.cpp
cd stable-diffusion.cpp
make

Q: Metal 加速不工作？

确保:

1. 使用 Apple Silicon Mac (M1/M2/M3)
2. macOS 版本 ≥ 12.0
3. stable-diffusion.cpp 编译时启用了 Metal 支持

License

MIT

🤝 Contributing

This project is in early development stage. All forms of contributions are welcome:

• 🐛 Report bugs (use Bug Report Template)
• 💡 Suggest features (use Feature Request Template)
• 📝 Improve documentation
• 🔧 Submit code fixes (read Contributing Guide)
• 🧪 Test on different environments and provide feedback

Check out Good First Issues to get started!

---

注意: 本项目处于早期开发阶段，部分功能可能尚未完成。