docs: 添加项目结构说明和使用示例章节

readme.md

@@ -7,3 +7,133 @@
 > 1. 该脚本只是一个简单的示例，不保证任何的稳定性。
 > 2. 请根据自己的需求进行修改。
 
+## 项目结构
+
+项目包含多个可独立部署的服务栈，每个服务栈位于单独的目录中，包含以下核心文件：
+- `stack.yml` / `compose.yml` - Docker Compose 配置文件
+- `env.cfg` - 环境变量配置文件（包含敏感信息，已 gitignore）
+- `env.cfg.example` - 环境变量配置模板（不含敏感信息）
+- `readme.md` - 服务说明文档（可选）
+
+## 使用示例
+
+### Gitea 部署实践事例
+
+**场景**：要部署 Gitea 服务，但希望保持项目目录的原始配置不变，同时在独立的目录中进行定制化部署。
+
+**1. 创建独立部署目录**：
+```bash
+# 假设当前在 deploy.stack 项目根目录
+# 创建独立的部署目录
+mkdir -p ~/mydeploy
+cd ~/mydeploy
+
+# 复制项目中的 Gitea 配置（相对路径或绝对路径）
+cp -r ../deploy.stack/gitea .
+# 或者使用绝对路径
+# cp -r /path/to/your/deploy.stack/gitea .
+
+# 进入 Gitea 目录
+cd gitea
+```
+
+**2. 准备环境变量**：
+```bash
+# 复制环境变量模板
+cp env.cfg.example env.cfg
+
+# 编辑环境变量（根据实际需求修改）
+vim env.cfg
+```
+
+**3. 修改配置（在 mydeploy 目录中）**：
+
+**修改端口映射**（Gitea 默认使用 3000 端口，可能与 Grafana 冲突）：
+```yaml
+# 在 lky-prod.yml 或 rpi-prod.yml 中添加端口映射
+ports:
+  - "3001:3000"  # 将容器内 3000 端口映射到宿主机 3001 端口
+```
+
+**调整数据卷路径**（根据实际存储位置）：
+```bash
+# 在 env.cfg 中修改 Volumes_Path
+Volumes_Path=/data/volumes/gitea
+```
+
+**更新镜像版本**：
+```bash
+# 在 env.cfg 中修改镜像版本
+IMAGE_TAG_VER=1.25.2
+IMAGE_TAG=gitea/gitea:${IMAGE_TAG_VER}-rootless
+```
+
+**选择环境配置文件**：
+- `lky-prod.yml` - 用于生产环境（Linux 服务器）
+- `rpi-prod.yml` - 用于树莓派环境
+- 根据实际环境选择合适的 compose 文件
+
+**4. 创建数据目录**：
+```bash
+# 根据 env.cfg 中的 Volumes_Path 创建目录
+mkdir -pv /data/volumes/gitea/{data,config,logs}
+
+# 设置正确的权限（Gitea 使用 UID 1000）
+chown -R 1000:1000 /data/volumes/gitea/
+```
+
+**5. 部署服务**：
+```bash
+# 拉取镜像（根据选择的配置文件）
+docker compose -p gitea --env-file ./env.cfg -f ./lky-prod.yml pull
+# 或使用 rpi-prod.yml
+# docker compose -p gitea --env-file ./env.cfg -f ./rpi-prod.yml pull
+
+# 启动服务
+docker compose -p gitea --env-file ./env.cfg -f ./lky-prod.yml up -d
+
+# 查看日志
+docker compose -p gitea --env-file ./env.cfg -f ./lky-prod.yml logs -f
+
+# 查看服务状态
+docker compose -p gitea --env-file ./env.cfg -f ./lky-prod.yml ps
+
+# 停止服务
+docker compose -p gitea --env-file ./env.cfg -f ./lky-prod.yml down
+```
+
+**6. 优势**：
+- **配置隔离**：在 `mydeploy` 目录中的修改不会影响原始项目配置
+- **版本管理**：可以针对不同环境维护不同的配置版本
+- **快速回滚**：如需恢复原始配置，只需删除 `mydeploy` 目录并重新部署
+- **测试验证**：可以在 `mydeploy` 中测试新配置，确认无误后再应用到生产环境
+
+**7. 注意事项**：
+- **配置兼容性**：确保 `mydeploy` 目录中的配置文件与原始项目保持兼容，特别是 compose 文件版本
+- **定期同步**：关注原始项目的更新（安全补丁、新功能等），适时同步到 `mydeploy` 目录
+- **配置备份**：定期备份 `mydeploy` 目录中的自定义配置
+- **敏感信息安全**：`env.cfg` 包含密码、密钥等敏感信息，确保文件权限为 600
+```bash
+chmod 600 env.cfg
+```
+- **版本控制**：建议将 `mydeploy` 目录纳入版本控制（排除 `env.cfg`）
+- **多环境管理**：可以为不同环境创建不同的 `mydeploy` 目录，如 `mydeploy-prod`、`mydeploy-dev`
+
+**8. 通用模式**：
+这种 "mydeploy" 模式不仅适用于 Gitea，也适用于项目中的其他服务：
+
+```bash
+# 部署 Grafana
+cp -r ../deploy.stack/grafana ~/mydeploy/grafana
+
+# 部署 Memos
+cp -r ../deploy.stack/memos ~/mydeploy/memos
+
+# 部署 Portainer
+cp -r ../deploy.stack/portainer-ce ~/mydeploy/portainer-ce
+
+# 部署 Traefik
+cp -r ../deploy.stack/traefik ~/mydeploy/traefik
+```
+
+每个服务都可以在独立的目录中进行定制化配置和测试，实现真正的配置隔离和环境管理。