README_CN.md
Rama main · réplica de lectura del repositorio original.
# Ithiltir Dash [](https://github.com/Ithildur/Ithiltir/releases) [](https://github.com/Ithildur/Ithiltir/releases) [](LICENSE)
Ithiltir 是一套自托管服务器监控系统。Dash 集中接收节点上报，并在一个进程内提供看板、历史指标、流量统计、告警和管理功能。
[English](README.md) · [在线文档](https://www.ithiltir.dev/) · [快速开始](https://www.ithiltir.dev/docs/QuickStart) · [Demo](https://demo.ithiltir.dev/) · [Ithiltir-node](https://github.com/Ithildur/Ithiltir-node)
## 界面预览
## 功能
- CPU、内存、磁盘、网络、温度、进程和连接数实时指标
- 基于 PostgreSQL 和 TimescaleDB 的在线率数据与指标历史
- RAID、SMART、NVMe critical warning 和 Proxmox VE 宿主机支持
- 月度流量、可配置账期和 95 计费数据
- 告警规则、事件记录，以及 Telegram、SMTP 或 Webhook 通知
- 节点分组、搜索、游客可见范围、主题和系统管理
- Linux、macOS 和 Windows Node 安装与更新
## 安装
Dash 发布包支持 Linux amd64 和 arm64。安装最新稳定版：
```bash
ARCH=amd64
curl -fL -o "Ithiltir_dash_linux_${ARCH}.tar.gz" \
"https://github.com/Ithildur/Ithiltir/releases/latest/download/Ithiltir_dash_linux_${ARCH}.tar.gz"
tar -xzf "Ithiltir_dash_linux_${ARCH}.tar.gz"
cd Ithiltir-dash
sudo bash install_dash_linux.sh --lang zh --service-manager=systemd
```
AArch64 机器使用 `ARCH=arm64`。在受支持的 Debian/Ubuntu 系统上，安装器可以准备 PostgreSQL、TimescaleDB、Redis、数据库迁移和 systemd 服务；其他部署方式见[安装文档](https://www.ithiltir.dev/docs/Install)。
安装完成后访问配置的 `app.public_url`，在地址后加 `/login` 进入管理台。创建节点后，按管理台生成的命令安装 Node。
正式发布包包含可选 PVE VM 监控所需的采集工具；自行打包时需使用 `scripts/package.sh --with-pve`。在管理台复制 PVE 安装命令并在 PVE 宿主机执行，安装器会启用 helper 和 gRPC 传输；反向代理需转发 gRPC。点击宿主机卡片上的 PVE 系统图标可查看 VM 列表；展开对应 VM 行即可查看详情和历史指标，也可全部展开或折叠。游客访问默认关闭，可在系统设置中开启，且仅适用于游客可见的宿主机。游客只看 VM 列表和当前指标，不展示 IP；名称需明确开启展示。详情和历史曲线仅管理员可见。安装、更新和停用方式见 [Node 部署说明](deploy/node/README.md#optional-pve-monitoring)。
## 源码运行
源码开发需要 Go 1.27.3+、Bun 1.3.11、PostgreSQL 16+ 及对应主版本的 TimescaleDB。除非用 `--no-redis` 启动，否则还需要 Redis。
```bash
cp configs/config.example.yaml config.local.yaml
# 继续前请替换所有 __...__ 占位符。
export monitor_dash_pwd='<password>'
go run ./cmd/dash migrate -config config.local.yaml
go run ./cmd/dash -debug
```
管理员密码至少包含 8 个可见 ASCII 字符，且不能有空白。完整源码配置见[快速开始](https://www.ithiltir.dev/docs/QuickStart)。
## 运行注意事项
- Dash 是单实例应用，不能让多个 Dash 进程同时写同一套状态。
- `app.public_url` 必须是根路径 URL，不支持 `/dash` 这类路径前缀。
- 不可信网络使用 HTTPS；浏览器、API、主题和部署资产应保持同源。
- Redis 默认保存管理员会话和可丢弃的前台状态；`--no-redis` 模式改用进程内存，重启后失效。
- `$DASH_HOME/configs/notify-config.key` 必须与 PostgreSQL 分开备份；丢失匹配密钥后无法恢复通知渠道凭据。
数据保留、容量规划、备份、反向代理和安全说明见[运维文档](https://www.ithiltir.dev/docs/Operations)。
## 更新
```bash
/opt/Ithiltir-dash/bin/dash update --check
sudo /opt/Ithiltir-dash/bin/dash update
sudo /opt/Ithiltir-dash/bin/dash update --test
```
默认通道安装稳定版，`--test` 选择预发布版。如果迁移中断后需要恢复：
```bash
sudo /opt/Ithiltir-dash/bin/dash update recover
```
跨越带迁移说明的版本前，先阅读[破坏性变更](docs/breaking-changes_CN.md)。
## 开发
```bash
go test ./...
cd web
bun run lint
bun run typecheck
```
数据库集成测试需要设置 `TEST_DATABASE_URL`。前端开发可以代理一个正在运行的 Dash：
```bash
cd web
FRONT_TEST_API=http://127.0.0.1:8080 bun run dev
```
构建前端和 Linux 安装包：
```bash
bash scripts/build_frontend.sh -o build/frontend/dist
bash scripts/package.sh --with-pve \
-o release -t linux/amd64 --tar-gz
```
本地 Node 资产布局见 [deploy/node/README.md](deploy/node/README.md)。
## 文档
| 文档 | 内容 |
| ---------------------------------------------------- | ---------------------------------- |
| [快速开始](https://www.ithiltir.dev/docs/QuickStart) | 安装 Dash 并接入第一个节点 |
| [安装部署](https://www.ithiltir.dev/docs/Install) | 生产部署、反向代理、平台和升级 |
| [运维](https://www.ithiltir.dev/docs/Operations) | 备份、保留期、容量、安全和排错 |
| [架构](docs/architecture_CN.md) | 运行边界、数据流、存储、告警和更新 |
| [API](docs/api_CN.md) | HTTP 路径和上报契约 |
| [破坏性变更](docs/breaking-changes_CN.md) | 迁移和兼容说明 |
## 许可证
AGPL-3.0-only。见 [LICENSE](LICENSE)。
## Node gRPC 传输
为兼容已有安装，默认仍使用 HTTP。在 Node 服务环境中设置 `ITHILTIR_NODE_TRANSPORT=grpc`（仅 RPC）或 `auto`（发送报告前协商），再重启 Node。Dash 在现有 HTTP/2 监听地址提供 gRPC；代理必须以 gRPC 转发 `/ithiltir.node.v1.Node/`。这两种模式不会因鉴权或 TLS 失败降级到明文。PVE 历史还要求 root helper 常驻服务（`pve-cache`）。浏览器 API 和资产下载继续使用 HTTP。