From 19782e8393f5ff7f02f18ab5775d8ea573b08df2 Mon Sep 17 00:00:00 2001
From: moqiruyi <moqiruyi@gmail.com>
Date: Thu, 18 Jun 2026 15:27:03 +0800
Subject: [PATCH] feat(grafana): add deployment documentation

---
 grafana/readme.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 grafana/readme.md

diff --git a/grafana/readme.md b/grafana/readme.md
new file mode 100644
index 0000000..0b54278
--- /dev/null
+++ b/grafana/readme.md
@@ -0,0 +1,69 @@
+# Grafana 部署说明
+
+[Grafana](https://grafana.com/) 是一个开源的可观测性平台，支持 Prometheus、InfluxDB、Loki、Elasticsearch 等多种数据源，提供丰富的仪表盘和告警能力，适用于基础设施监控、应用性能分析和日志可视化等场景。
+
+## 目录结构
+
+| 文件 | 说明 |
+|------|------|
+| `compose.yml` | Docker Compose 部署配置 |
+| `env.cfg` | 环境变量（镜像版本） |
+| `env.cfg.example` | 环境变量模板（不含敏感信息） |
+
+## 部署命令
+
+```bash
+# 拉取镜像
+docker compose -p grafana --env-file ./grafana/env.cfg -f ./grafana/compose.yml pull
+
+# 启动服务
+docker compose -p grafana --env-file ./grafana/env.cfg -f ./grafana/compose.yml up -d
+
+# 停止服务
+docker compose -p grafana --env-file ./grafana/env.cfg -f ./grafana/compose.yml down
+
+# 查看日志
+docker compose -p grafana --env-file ./grafana/env.cfg -f ./grafana/compose.yml logs -f
+```
+
+## 环境变量说明
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `IMAGE_TAG_VER` | Grafana 镜像版本 | `13.0.2` |
+| `IMAGE_TAG` | 完整镜像标签 | `grafana/grafana:13.0.2` |
+
+## 访问服务
+
+- 默认端口：`3000`
+- 访问地址：`http://<主机IP>:3000`
+- 默认登录凭据：`admin / admin`（首次登录后建议修改密码）
+
+## 持久化
+
+当前配置使用无状态模式，容器重启后仪表盘和配置会丢失。如需持久化，建议在 `compose.yml` 中添加卷挂载：
+
+```yaml
+services:
+  grafana:
+    volumes:
+      - ${Volumes_Path:-/data/volumes/grafana}:/var/lib/grafana   # 数据持久化
+```
+
+并确保宿主机目录权限正确：
+
+```bash
+# 创建数据目录
+mkdir -pv /data/volumes/grafana
+
+# 设置目录属主为 Grafana 容器用户（UID 472）
+chown -R 472:472 /data/volumes/grafana
+```
+
+## 注意事项
+
+- Grafana 和 Gitea 默认都使用 3000 端口，部署在同一宿主机时需通过 `env.cfg` 或 compose 调整端口映射避免冲突
+- 容器使用 `restart: unless-stopped` 策略，宿主机重启后自动拉起
+- 默认使用匿名用户访问，如需接入 LDAP/OAuth 等认证，需挂载自定义 `grafana.ini` 配置文件
+- 生产环境建议配置数据源和告警渠道的持久化存储
+- 当前 `env.cfg.example` 版本为 `13.0.2`，实际部署版本以 `env.cfg` 为准
\ No newline at end of file