feat: update Guidelines

README.zh.md

@@ -67,37 +67,50 @@ Compose Anything 通过提供一组高质量的 Docker Compose 配置文件，
 
 ## 规范
 
-1. **开箱即用**，配置应该是开箱即用的，无需配置也能启动（最多提供 `.env` 文件）；
-2. **命令简单**
+1. 开箱即用
+    - 配置应该是开箱即用的，无需额外步骤即可启动（最多提供 `.env` 文件）。
+2. 命令简单
     - 每个项目提供单一的 `docker-compose.yaml` 文件；
-    - 命令的复杂性避免超过 `docker compose` 命令，如果超过请提供 `Makefile`；
-    - 如果服务需要初始化，可借助 `depends_on` 模拟 Init 容器；
-3. **版本稳定**
-    - 提供一个最新稳定的镜像版本而不是 `latest`；
-    - 允许通过环境变量配置版本号；
-4. **充分可配置**
-    - 尽量通过环境变量配置，而不是通过复杂的命令行参数；
-    - 环境变量，密码等敏感信息应通过环境变量或挂载文件传递，不要硬编码；
-    - 提供合理默认值，尽量零配置能启动；
-    - 尽可能提供 `.env.example` 文件并有注释，帮助用户快速上手；
-    - 如果是非必要依赖，请使用 Profiles 配置；
-5. **跨平台**，（在镜像支持的情况下）请确保主流平台都能正常启动；
-    - 兼容标准是：Debian 12+/Ubuntu 22.04+、Windows 10+、macOS 12+；
-    - 尽可能兼容不同的架构，如 x86-64、ARM64；
-6. **小心处理挂载**
-    - 配置文件尽量使用相对路径挂载，确保跨平台兼容性；
-    - 数据目录尽量使用命名卷，避免主机路径挂载带来的权限和兼容性问题；
-7. **默认资源限制**
-    - 对每个服务限制 CPU 和内存使用，防止意外的资源耗尽；
-    - 限制日志的大小，防止日志文件占满磁盘；
-    - 对于 GPU 服务默认启用单卡；
-8. **文档全面**
-    - 提供良好的文档和示例，帮助用户快速上手和理解配置；
-    - 特别要提供如何初始化账户，管理员账户等说明；
-    - 必要时，提供安全和许可说明；
-    - 提供 LLM 友好的文档，方便用户使用 LLM 进行查询和理解；
-9. **最佳实践**，遵循其他可能的最佳实践，确保安全性、性能和可维护性。
+    - 命令复杂度不应超过 `docker compose up -d`；若需要额外流程，请提供 `Makefile`；
+    - 若服务需要初始化，优先使用 `healthcheck` 与 `depends_on` 的 `condition: service_healthy` 组织启动顺序。
+3. 版本稳定
+    - 固定到“最新稳定版”而非 `latest`；
+    - 通过环境变量暴露镜像版本（如 `FOO_VERSION`）。
+4. 配置约定
+    - 尽量通过环境变量配置，而非复杂的命令行参数；
+    - 敏感信息通过环境变量或挂载文件传递，不要硬编码；
+    - 提供合理默认值，实现零配置可启动；
+    - 必须提供带注释的 `.env.example`；
+    - 环境变量命名建议：全大写、下划线分隔，按服务加前缀（如 `POSTGRES_*`），端口覆写统一用 `*_PORT_OVERRIDE`。
+5. Profiles 规范
+    - 对“可选组件/依赖”使用 Profiles；
+    - 推荐命名：`gpu`（GPU 加速）、`metrics`（可观测性/导出器）、`dev`（开发特性）。
+6. 跨平台与架构
+    - 在镜像支持前提下，确保 Debian 12+/Ubuntu 22.04+、Windows 10+、macOS 12+ 可用；
+    - 支持 x86-64 与 ARM64 架构尽可能一致；
+    - 避免依赖仅在 Linux 主机存在的主机路径（例如 `/etc/localtime`、`/etc/timezone`），统一使用 `TZ` 环境变量传递时区。
+7. 卷与挂载
+    - 配置文件优先使用相对路径，增强跨平台兼容；
+    - 数据目录优先使用“命名卷”，避免主机路径权限/兼容性问题；
+    - 如需主机路径，建议提供顶层目录变量（如 `DATA_DIR`）。
+8. 资源与日志
+    - 必须限制 CPU/内存，防止资源打爆；
+    - GPU 服务默认单卡：可使用 `deploy.resources.reservations.devices`（Compose 支持为 device_requests 映射）或 `gpus`；
+    - 限制日志大小（`json-file`：`max-size`/`max-file`）。
+9. 健康检查
+    - 每个服务应提供 `healthcheck`，包括合适的 `interval`、`timeout`、`retries` 与 `start_period`；
+    - 依赖链通过 `depends_on.condition: service_healthy` 组织。
+10. 安全基线（能用则用）
+    - 以非 root 运行（提供 `PUID`/`PGID` 或直接 `user: "1000:1000"`）；
+    - 只读根文件系统（`read_only: true`），必要目录使用 `tmpfs`/可写挂载；
+    - 最小权限：`cap_drop: ["ALL"]`，按需再 `cap_add`；
+    - 避免使用 `container_name`（影响可扩缩与复用网络别名）；
+    - 如需暴露 Docker 套接字等高危挂载，必须在文档中明确“风险与替代方案”。
+11. 文档与可发现性
+    - 提供清晰文档与示例（含初始化与管理员账号说明、必要的安全/许可说明）；
+    - 提供对 LLM 友好的结构化文档；
+    - 在 README 中标注主要环境变量与默认端口，并链接到 `README.md` / `README.zh.md`。
 
 ## 开源协议
 
-MIT License.
+[MIT License](./LICENSE).