help-14/magma
GitHub: help-14/magma
一款基于 SvelteKit 的可定制轻量个人仪表盘，配备无边界网格 widget 编辑器与 Docker 部署支持，帮助用户自由搭建个性化起始页和监控面板。
Stars: 47 | Forks: 6
# Magma
一款可定制的 SvelteKit 仪表盘应用，配备基于网格的 widget 编辑器、多语言支持以及 Docker 部署。
## 功能
- **网格仪表盘编辑器** — 在无边界的居中网格上拖拽、调整大小和排列 widget，并支持单元尺寸吸附。编辑模式可切换拖拽栏、调整大小控制柄以及浮动 widget 面板。
- **Widget 系统** — 内置 widget 包括：
- **Button** — 带有图标选择器的链接启动器
- **Search** — 带有可配置提供商的搜索栏
- **Timer** — 倒计时 / 秒表计时器
- **Weather** — 带有位置预设的实时天气显示
- **Calendar** — 日期和事件视图
- **Stack (horizontal / vertical)** — 将子 widget 分组为行或列
- **Docker Status** — 监控容器状态
- **Service Status** — HTTP endpoint 健康检查
- **Fetch** — 显示来自任意 URL 的内容
- **DeepSeek** — 账户余额和 token 使用情况监视器
- **设置面板** — 三个配置部分：
- **System** — 网格尺寸（单元格宽/高）、背景图片、语言
- **Dashboard** — Widget 布局、搜索、网络、主题和集成引用
- **CSS** — 在内置样式之后加载的自定义 CSS 覆盖
- **国际化** — 通过 [inlang](https://inlang.com) / [Paraglide JS](https://paraglidejs.com) 实现 i18n。内置英语和越南语。
- **远程函数** — 通过 SvelteKit 远程函数为 widget 提供服务端数据获取。
- **深色主题** — 温暖的深色半透明面板，配以黄色点缀。由 [shadcn-svelte](https://shadcn-svelte.com) 组件和 [Tailwind CSS 4](https://tailwindcss.com) 提供支持。
- **Docker 支持** — 多阶段 Docker 构建和用于生产部署的 `docker-compose.yml`。
## 快速开始
### 前置条件
- [Node.js](https://nodejs.org/) >= 26
- [pnpm](https://pnpm.io/installation)
### 安装
```
pnpm install
```
### 开发
```
pnpm dev
```
开发服务器将在 `http://localhost:5173` 启动。
### 构建与预览
```
pnpm build
pnpm preview
```
### 类型检查
```
pnpm check
```
## 配置
所有配置都存放在项目根目录下的 `config/` 目录中。在 Docker 部署中，该目录会作为 volume 挂载。
| 文件 | 用途 |
| ----------------------- | -------------------------------------------------------------------------- |
| `config/system.yaml` | 应用级设置（网格尺寸、背景图片、语言） |
| `config/dashboard.yaml` | Widget 布局、主题、搜索提供商、网络和集成引用 |
| `config/override.css` | 自定义 CSS 覆盖（在内置样式之后加载） |
YAML 中引用的环境变量（例如用于 API token 的）会在运行时解析。密钥**绝不**应直接提交到 YAML 文件中。
## Docker
```
docker compose up -d
```
应用监听端口 `3000`。`config/` 中的配置文件会自动挂载到容器的 `/config` 目录下。
用于生产环境的环境变量：
| 变量 | 默认值 | 描述 |
| ------------ | ----------------------- | ------------------------------------- |
| `NODE_ENV` | `production` | 运行时环境 |
| `HOST` | `0.0.0.0` | 服务器绑定地址 |
| `PORT` | `3000` | 服务器端口 |
| `ORIGIN` | `http://localhost:3000` | 公共 URL（用于 CSRF 保护） |
| `CONFIG_DIR` | `/config` | 配置目录的路径 |
## 项目结构
```
magma/
├── config/ # Runtime configuration (YAML + CSS)
│ ├── dashboard.yaml
│ ├── system.yaml
│ └── override.css
├── docs/ # Design specs and planning
├── messages/ # i18n translation files
│ ├── en.json
│ └── vi.json
├── src/
│ ├── lib/
│ │ ├── components/ # Svelte components
│ │ │ ├── dashboard/ # Dashboard editor, widget palette, property panels
│ │ │ ├── settings/ # Settings panel
│ │ │ └── ui/ # shadcn-svelte UI primitives
│ │ ├── hooks/ # Svelte reusable logic
│ │ ├── paraglide/ # Auto-generated i18n (via inlang)
│ │ ├── remotes/ # Server remote functions
│ │ ├── server/ # Server-only code (config I/O, etc.)
│ │ └── types/ # JSDoc type definitions
│ ├── routes/ # SvelteKit pages and API endpoints
│ │ ├── (dashboard)/ # Main dashboard page + editor
│ │ ├── api/ # REST API endpoints
│ │ └── settings/ # Settings page
│ └── app.html # HTML shell
├── static/ # Static assets
├── build/ # Production build output
├── Dockerfile
├── docker-compose.yml
└── package.json
```
## 仪表盘编辑器
- 网格画布覆盖整个视口并**水平居中**（页面中心为 x=0）。
- Widget 位置采用**居中坐标系** —— 负 x 在中心左侧，正 x 在右侧。
- 网格是**无边界**的 —— 没有固定的列或行限制。仅强制限制重叠。
- **单元尺寸**可在“设置 → System”中配置（`cellWidth` / `cellHeight`，默认为 100×100 px）。
- 在**编辑模式**下，会按单元尺寸间隔显示网格线，并突出显示黄色的中心线。
- 通过拖拽 widget 顶部的拖拽栏来移动它们；在编辑模式下悬停时会显示调整大小控制柄。
- **添加 Widget** 会打开一个底部的浮动面板。放下 widget 时，会从落点起扫描 ±20 个单元格，以寻找最近的空闲位置。
- 更改不会自动保存 —— 请按**完成**以保存布局。
## Widgets
Widget 定义在 `config/dashboard.yaml` 中的 `dashboard.widgets` 下。每个 widget 都具有：
```
- id: my-widget
type: button # One of the supported widget types
title: My Widget
x: 0 # Grid X position (centered)
y: 0 # Grid Y position
w: 4 # Width in cells
h: 2 # Height in cells
config: {} # Type-specific configuration
```
Stack 可以包含子 widget：
```
- id: my-stack
type: stack-horizontal
title: Launchers
x: -5
y: 2
w: 10
h: 2
config:
gap: 12
children:
- id: app-1
type: button
title: App 1
config:
icon: lucide:globe
url: https://example.com
```
## 远程函数
服务端数据获取是通过 `src/lib/remotes/*.remote.js` 中的 SvelteKit 远程函数实现的。它们为需要实时数据的 widget（天气、Docker 状态、DeepSeek 余额等）提供了一个类型安全的 RPC 层。
## 许可证
MIT
## 功能
- **网格仪表盘编辑器** — 在无边界的居中网格上拖拽、调整大小和排列 widget，并支持单元尺寸吸附。编辑模式可切换拖拽栏、调整大小控制柄以及浮动 widget 面板。
- **Widget 系统** — 内置 widget 包括：
- **Button** — 带有图标选择器的链接启动器
- **Search** — 带有可配置提供商的搜索栏
- **Timer** — 倒计时 / 秒表计时器
- **Weather** — 带有位置预设的实时天气显示
- **Calendar** — 日期和事件视图
- **Stack (horizontal / vertical)** — 将子 widget 分组为行或列
- **Docker Status** — 监控容器状态
- **Service Status** — HTTP endpoint 健康检查
- **Fetch** — 显示来自任意 URL 的内容
- **DeepSeek** — 账户余额和 token 使用情况监视器
- **设置面板** — 三个配置部分：
- **System** — 网格尺寸（单元格宽/高）、背景图片、语言
- **Dashboard** — Widget 布局、搜索、网络、主题和集成引用
- **CSS** — 在内置样式之后加载的自定义 CSS 覆盖
- **国际化** — 通过 [inlang](https://inlang.com) / [Paraglide JS](https://paraglidejs.com) 实现 i18n。内置英语和越南语。
- **远程函数** — 通过 SvelteKit 远程函数为 widget 提供服务端数据获取。
- **深色主题** — 温暖的深色半透明面板，配以黄色点缀。由 [shadcn-svelte](https://shadcn-svelte.com) 组件和 [Tailwind CSS 4](https://tailwindcss.com) 提供支持。
- **Docker 支持** — 多阶段 Docker 构建和用于生产部署的 `docker-compose.yml`。
## 快速开始
### 前置条件
- [Node.js](https://nodejs.org/) >= 26
- [pnpm](https://pnpm.io/installation)
### 安装
```
pnpm install
```
### 开发
```
pnpm dev
```
开发服务器将在 `http://localhost:5173` 启动。
### 构建与预览
```
pnpm build
pnpm preview
```
### 类型检查
```
pnpm check
```
## 配置
所有配置都存放在项目根目录下的 `config/` 目录中。在 Docker 部署中，该目录会作为 volume 挂载。
| 文件 | 用途 |
| ----------------------- | -------------------------------------------------------------------------- |
| `config/system.yaml` | 应用级设置（网格尺寸、背景图片、语言） |
| `config/dashboard.yaml` | Widget 布局、主题、搜索提供商、网络和集成引用 |
| `config/override.css` | 自定义 CSS 覆盖（在内置样式之后加载） |
YAML 中引用的环境变量（例如用于 API token 的）会在运行时解析。密钥**绝不**应直接提交到 YAML 文件中。
## Docker
```
docker compose up -d
```
应用监听端口 `3000`。`config/` 中的配置文件会自动挂载到容器的 `/config` 目录下。
用于生产环境的环境变量：
| 变量 | 默认值 | 描述 |
| ------------ | ----------------------- | ------------------------------------- |
| `NODE_ENV` | `production` | 运行时环境 |
| `HOST` | `0.0.0.0` | 服务器绑定地址 |
| `PORT` | `3000` | 服务器端口 |
| `ORIGIN` | `http://localhost:3000` | 公共 URL（用于 CSRF 保护） |
| `CONFIG_DIR` | `/config` | 配置目录的路径 |
## 项目结构
```
magma/
├── config/ # Runtime configuration (YAML + CSS)
│ ├── dashboard.yaml
│ ├── system.yaml
│ └── override.css
├── docs/ # Design specs and planning
├── messages/ # i18n translation files
│ ├── en.json
│ └── vi.json
├── src/
│ ├── lib/
│ │ ├── components/ # Svelte components
│ │ │ ├── dashboard/ # Dashboard editor, widget palette, property panels
│ │ │ ├── settings/ # Settings panel
│ │ │ └── ui/ # shadcn-svelte UI primitives
│ │ ├── hooks/ # Svelte reusable logic
│ │ ├── paraglide/ # Auto-generated i18n (via inlang)
│ │ ├── remotes/ # Server remote functions
│ │ ├── server/ # Server-only code (config I/O, etc.)
│ │ └── types/ # JSDoc type definitions
│ ├── routes/ # SvelteKit pages and API endpoints
│ │ ├── (dashboard)/ # Main dashboard page + editor
│ │ ├── api/ # REST API endpoints
│ │ └── settings/ # Settings page
│ └── app.html # HTML shell
├── static/ # Static assets
├── build/ # Production build output
├── Dockerfile
├── docker-compose.yml
└── package.json
```
## 仪表盘编辑器
- 网格画布覆盖整个视口并**水平居中**（页面中心为 x=0）。
- Widget 位置采用**居中坐标系** —— 负 x 在中心左侧，正 x 在右侧。
- 网格是**无边界**的 —— 没有固定的列或行限制。仅强制限制重叠。
- **单元尺寸**可在“设置 → System”中配置（`cellWidth` / `cellHeight`，默认为 100×100 px）。
- 在**编辑模式**下，会按单元尺寸间隔显示网格线，并突出显示黄色的中心线。
- 通过拖拽 widget 顶部的拖拽栏来移动它们；在编辑模式下悬停时会显示调整大小控制柄。
- **添加 Widget** 会打开一个底部的浮动面板。放下 widget 时，会从落点起扫描 ±20 个单元格，以寻找最近的空闲位置。
- 更改不会自动保存 —— 请按**完成**以保存布局。
## Widgets
Widget 定义在 `config/dashboard.yaml` 中的 `dashboard.widgets` 下。每个 widget 都具有：
```
- id: my-widget
type: button # One of the supported widget types
title: My Widget
x: 0 # Grid X position (centered)
y: 0 # Grid Y position
w: 4 # Width in cells
h: 2 # Height in cells
config: {} # Type-specific configuration
```
Stack 可以包含子 widget：
```
- id: my-stack
type: stack-horizontal
title: Launchers
x: -5
y: 2
w: 10
h: 2
config:
gap: 12
children:
- id: app-1
type: button
title: App 1
config:
icon: lucide:globe
url: https://example.com
```
## 远程函数
服务端数据获取是通过 `src/lib/remotes/*.remote.js` 中的 SvelteKit 远程函数实现的。它们为需要实时数据的 widget（天气、Docker 状态、DeepSeek 余额等）提供了一个类型安全的 RPC 层。
## 许可证
MIT标签：Docker, SvelteKit, 个人仪表盘, 安全防御评估, 组件化, 自托管, 请求拦截