forked from DevOps/deploy.stack
chore: add env.cfg.example templates and clean up config files
This commit is contained in:
cnphpbb
@@ -7,9 +7,9 @@
|
||||
```
|
||||
<service>/
|
||||
├── stack.yml / compose.yml / <env>.stack.yml / <env>.yml # Docker Compose 文件
|
||||
├── env.cfg # 环境变量（含敏感信息，应 gitignore）
|
||||
├── readme.md # 服务说明文档（可选）
|
||||
└── config/ # 服务配置文件（可选）
|
||||
├── env.cfg.example # 环境变量（含敏感信息，应 gitignore）
|
||||
├── readme.md # 服务说明文档（可选）
|
||||
└── config/ # 服务配置文件（可选）
|
||||
```
|
||||
|
||||
顶层目录按职责划分：
|
||||
@@ -132,6 +132,7 @@ docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/gola
|
||||
- **国内镜像源**：Dockerfile 和 apt 配置默认使用国内 CDN 镜像（中科大、阿里云、华为），部署在其他地区需修改。
|
||||
- **Portainer Docker 兼容性**：Portainer CE LTS < 2.36.0 不兼容 Docker >= 29.0.0，需设置 `DOCKER_MIN_API_VERSION=1.24`。详见 `portainer-ce/readme.md`。
|
||||
- **i2c.py 需要硬件**：OLED 显示脚本需要树莓派 I2C 硬件、`adafruit_ssd1306` 库和中文字体（`fonts-wqy-microhei`）。
|
||||
- **shell 脚本禁用 CRLF**：仓库根目录的 `.gitattributes` 已强制 `*.sh` / `*.bash` / `*.py` / `*.md` / `*.yml` / `*.cfg` 等文本 LF 行尾。Windows 工具（IDE agent、记事本、PowerShell）默认写 CRLF，会导致 Linux 上 `'\r': 未找到命令` 和 `function xxx() {` 语法错误。**新建或修改脚本后必须 `file <script>` 验证输出不含 `CRLF line terminators`**，如果命中立即 `sed -i 's/\r$//' <script>` 修正。
|
||||
|
||||
## 系统配置（etc/）
|
||||
|
||||
@@ -141,3 +142,261 @@ docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/gola
|
||||
- 连接队列大小（somaxconn、syn backlog）
|
||||
- 内存管理（swappiness、脏页阈值）
|
||||
- 安全加固（ICMP 重定向拒绝、反向路径过滤、kptr_restrict）
|
||||
|
||||
## Git 提交规范
|
||||
|
||||
### Commit Message 格式
|
||||
|
||||
本仓库 commit message **优先使用 Conventional Commits** 规范，与历史风格保持一致。格式：
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject> # 中文
|
||||
<type>(<scope>): <subject> # 英文
|
||||
```
|
||||
|
||||
### Type 类型
|
||||
|
||||
| Type | 用途 | 示例 |
|
||||
| ---------- | ------------------------------------ | --------------------------------------------- |
|
||||
| `feat` | 新增服务/新功能 | `feat: add adminer docker deployment files` |
|
||||
| `fix` | 修复 bug | `fix(gitea): 修复备份脚本权限问题` |
|
||||
| `docs` | 文档变更（readme、AGENTS.md 等） | `docs: 添加git提交信息规则文件` |
|
||||
| `refactor` | 重构（不改功能） | `refactor(status.py): 重构OLED状态显示代码` |
|
||||
| `perf` | 性能优化 | `perf(redis): 调整内存淘汰策略` |
|
||||
| `build` | 构建相关（Dockerfile、compose、依赖）| `build(moltbot): 添加生产环境docker compose` |
|
||||
| `chore` | 杂项（版本号、配置、镜像标签） | `chore: 更新 Joplin 服务器镜像版本至 3.6.1` |
|
||||
| `style` | 格式调整（不影响代码逻辑） | `style: 统一 yaml 缩进为 2 空格` |
|
||||
| `test` | 测试相关 | `test: 添加 memos 部署验证脚本` |
|
||||
|
||||
### Scope 范围（可选）
|
||||
|
||||
- 服务名（目录名小写）：`gitea`、`memos`、`haproxy`、`postgres`、`portainer-ce` 等
|
||||
- 顶层目录：`builder`、`crontab`、`etc`、`shell`、`i2c.py`
|
||||
- 省略：当改动跨多个服务或为全局性变更
|
||||
|
||||
### Subject 主题规则
|
||||
|
||||
1. **中文项目**用中文描述，**英文项目**用英文，统一保持
|
||||
2. **首字母小写**（中文不受影响）
|
||||
3. **不超过 50 个字符**，尽量精炼
|
||||
4. **不要句末加句号**
|
||||
5. **动词开头**：添加/更新/修复/重构/删除 或 add/update/fix/refactor/remove
|
||||
6. **写明对象**：要让人一眼看出改了什么
|
||||
|
||||
### Body 与 Footer（可选）
|
||||
|
||||
需要时换行后空一行写正文：
|
||||
|
||||
```
|
||||
feat(gitea): 添加 lfs 存储后端配置
|
||||
|
||||
- 使用 minio 作为 lfs 对象存储
|
||||
- 调整 gitea app.ini 路径映射
|
||||
- 备份脚本需同步调整
|
||||
|
||||
Refs: #123
|
||||
```
|
||||
|
||||
### 提交前自检
|
||||
|
||||
```bash
|
||||
# 1. 查看变更文件
|
||||
git status
|
||||
|
||||
# 2. 检查 diff 大小（避免误提交敏感文件）
|
||||
git diff --stat
|
||||
|
||||
# 3. 确认无 env.cfg / 凭据被误提交
|
||||
git diff | grep -iE "password|secret|token|key" # 应无敏感输出
|
||||
|
||||
# 4. 暂存并提交
|
||||
git add <files>
|
||||
git commit -m "<type>(<scope>): <subject>"
|
||||
|
||||
# 5. 推送
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 提交粒度
|
||||
|
||||
- **一个 commit 只做一件事**：不要把无关改动混在一起
|
||||
- **服务级别独立提交**：新增一个服务（如 `gitea/`）应该是独立 commit
|
||||
- **版本号更新单独 commit**：`chore(<service>): bump image tag to x.y.z`
|
||||
- **不要 commit 内容**：
|
||||
- `env.cfg`（含敏感信息，已 gitignore）
|
||||
- 编译产物（`*.bin`、`main`、`__pycache__/` 等）
|
||||
- IDE 配置（`.vscode/`、`.idea/`）
|
||||
- 系统级配置（`/data/volumes/` 下的实际数据）
|
||||
|
||||
### 历史风格兼容性
|
||||
|
||||
仓库早期 commit 有少量非 Conventional 风格（如 `Add lsd config and color theme`），
|
||||
**新增 commit 一律遵循本规范**，历史风格不强制改写。
|
||||
|
||||
### AI 生成 commit message 的硬约束
|
||||
|
||||
本小节是 `## AI 协作系统级约束` 章节在 commit 场景的具体执行规则。被要求生成 commit message 时，**只输出 commit text 本身**，严禁夹带任何元评论、解释或代码块包裹。
|
||||
|
||||
**输出黑名单（出现即视为违规）：**
|
||||
|
||||
- 前置说明：`我看了你的改动…`、`建议使用下面的 commit message：`、`以下为 commit：`
|
||||
- 元评论词汇：`分析`、`考虑`、`由于`、`因为`、`建议`、`注意`、`这里`、`本次`、`因为需要`
|
||||
- 复述 diff：把 `git diff` 的关键行直接放进 commit
|
||||
- 解释"为什么改"：commit 只描述"改了什么"，不写动机
|
||||
- 多版本候选/对比：不要 `Option 1 / Option 2` 或 `---begin--- / ---end---`
|
||||
- markdown 代码块包裹：直接给纯文本，除非用户明确要求
|
||||
|
||||
**输出前自检清单：**
|
||||
|
||||
- [ ] 只包含 commit text，无任何前后缀
|
||||
- [ ] subject ≤ 50 字符、无句末标点、动词开头、首字母小写
|
||||
- [ ] type 在 `{feat, fix, docs, refactor, perf, build, chore, style, test}` 内
|
||||
- [ ] scope 准确（服务名小写或顶层目录名）
|
||||
- [ ] body 每行 ≤ 72 字符、不重复 subject
|
||||
- [ ] 中英文不混用、保持与项目历史一致
|
||||
- [ ] 未泄露 `password|secret|token|key` 等敏感词
|
||||
|
||||
**正确示例：**
|
||||
|
||||
```
|
||||
feat(gitea): bump image to 1.25.2
|
||||
```
|
||||
|
||||
**错误示例（AI 常见错误）：**
|
||||
|
||||
```
|
||||
我看了你的改动，主要是更新了镜像版本，建议使用：
|
||||
|
||||
feat(gitea): bump image to 1.25.2
|
||||
|
||||
这次改动把版本从 1.24 升到 1.25.2，主要修复了…
|
||||
```
|
||||
|
||||
> **注意**：thinking 块属于模型内部推理，**无法在 commit 场景关闭**，但它对最终 commit 输出无污染。用户的关注点应放在“最终输出是否干净”。
|
||||
|
||||
## AI 协作系统级约束
|
||||
|
||||
本章定义 AI 助手在仓库内的系统级行为约束。`## Git 提交规范 > ### AI 生成 commit message 的硬约束` 是本约束在 commit 场景的具体执行规则，本章则覆盖所有 AI 协作场景的通用原则。
|
||||
|
||||
### 约束生效机制
|
||||
|
||||
AGENTS.md 全文在 **系统提示层级注入** AI 上下文（类似 CLAUDE.md / AGENTS.md 类机制的底层原理）。AI 收到本仓库相关请求时**必须先读取并应用**本约束——这是不可协商的，不是“参考文档”。
|
||||
|
||||
### 通用输出原则
|
||||
|
||||
任何场景下 AI 输出必须遵守：
|
||||
|
||||
- **不夹带元评论**：`我看了你的改动…`、`建议使用：…`、`以下为…`、`分析你的…` 等
|
||||
- **不复述 diff**：把 `git diff` 关键行直接复述到回复里
|
||||
- **不解释“为什么”**：commit 只描述“改了什么”，不写动机
|
||||
- **不多版本候选**：`Option 1 / Option 2`、`---begin--- / ---end---` 等
|
||||
- **不擅自 commit / push**：用户未明确要求时不执行 `git commit`、`git push`
|
||||
- **不修改敏感文件**：`env.cfg`、Harbor `compose.yaml`、`/data/volumes/` 数据
|
||||
- **不修改本文件**：AGENTS.md 由人类维护，AI 不得自行编辑
|
||||
|
||||
### thinking 块边界
|
||||
|
||||
- **thinking 块是模型内部推理**，在系统提示注入层之上，AI 无法控制是否生成
|
||||
- **Zed UI 折叠显示**属于编辑器行为，不在 AGENTS.md 约束范围
|
||||
- **判断“是否干净”看最终 commit text 本身**，不是 UI 渲染的折叠块
|
||||
- commit 文本里出现元评论 = AI 没遵守本约束，**不是 thinking 泄漏**
|
||||
|
||||
### 违规处理
|
||||
|
||||
- **轻微违规**（输出含元评论/复述 diff）：让 AI 重做，提示“严格按 AGENTS.md 系统级约束”
|
||||
- **严重违规**（擅自 commit/push、修改 env.cfg）：撤销操作 + 立即报告用户
|
||||
- **持续违规**：考虑切换非 reasoning 模型或降低 reasoning effort
|
||||
|
||||
## AGENTS.md 维护规则
|
||||
|
||||
AGENTS.md 是给 AI 助手（Claude Code、Codex、Hermes 等）和协作者阅读的项目宪法。
|
||||
它**不是写完就不动的文档**，而是要跟着仓库演进持续更新。
|
||||
|
||||
### 何时更新 AGENTS.md
|
||||
|
||||
出现以下情况之一，**必须**同步更新本文件（在同一个 PR/commit 或紧随其后）：
|
||||
|
||||
1. **新增/删除服务**：增减顶层服务目录（如新增 `gitea/`、下线 `flame/`）
|
||||
2. **架构变更**：目录结构、命名约定、文件组织方式发生调整
|
||||
3. **新增通用约定**：跨多个服务复用的规则（如新的环境变量命名、新的备份策略）
|
||||
4. **重大操作变更**：升级 Docker 版本、Compose 规范变更、镜像源切换
|
||||
5. **AI 助手踩坑**：发现 AI 反复犯同样的错误（如改 Harbor compose.yaml、提交 env.cfg）
|
||||
6. **私有仓库/凭据变动**：新增私有镜像仓库、凭据管理方式变化
|
||||
|
||||
### 何时**不**更新 AGENTS.md
|
||||
|
||||
- 单个服务的局部配置变更（写到该服务的 `readme.md`）
|
||||
- 镜像版本小版本号 bump（写到该服务 `chore` commit）
|
||||
- 一次性的 bug 修复
|
||||
- 与项目规范无关的个人偏好
|
||||
|
||||
### 内容质量要求
|
||||
|
||||
写给 AI 看的规则必须**明确、可执行、有上下文**：
|
||||
|
||||
- ✅ **好的写法**：
|
||||
> `harbor/compose.yaml` 是 `./prepare` 生成的输出文件，**不要手动修改**。
|
||||
- ❌ **差的写法**：
|
||||
> 注意 Harbor 的 compose 文件。
|
||||
|
||||
好的写法具备三要素：
|
||||
1. **是什么**（明确对象/文件/命令）
|
||||
2. **为什么**（背景/原因，让 AI 理解）
|
||||
3. **怎么办**（具体操作/替代方案）
|
||||
|
||||
### 章节组织
|
||||
|
||||
新增章节时遵循现有结构：
|
||||
|
||||
```markdown
|
||||
# 标题 + 简介
|
||||
|
||||
## 架构与组织
|
||||
## 服务规范
|
||||
## 部署与运维
|
||||
## 重要注意事项
|
||||
## 系统配置（etc/）
|
||||
## Git 提交规范
|
||||
## AGENTS.md 维护规则 ← 新章节放在最后
|
||||
```
|
||||
|
||||
- 章节顺序按 **"项目结构 → 规范 → 注意事项 → 工具/脚本 → 治理"** 排列
|
||||
- 新章节优先放在文档末尾，避免大改章节编号
|
||||
- 章节标题用 `##` 一级章节，**保持中文**（与全文风格一致）
|
||||
|
||||
### 更新流程建议
|
||||
|
||||
```bash
|
||||
# 1. 修改 AGENTS.md
|
||||
$EDITOR AGENTS.md
|
||||
|
||||
# 2. 单独提交（不要和服务代码改动混在一起）
|
||||
git add AGENTS.md
|
||||
git commit -m "docs: <本次更新的内容>"
|
||||
|
||||
# 3. 推送到远程
|
||||
git push origin main
|
||||
```
|
||||
|
||||
典型 commit 消息：
|
||||
- `docs: 补充 git 提交规范章节`
|
||||
- `docs: 新增 postgres 服务的部署注意事项`
|
||||
- `docs: 更新 AGENTS.md 维护规则`
|
||||
- `docs: 修正 harbor compose.yaml 描述`
|
||||
|
||||
### 验证清单
|
||||
|
||||
每次更新后过一遍：
|
||||
|
||||
- [ ] 章节顺序合理，编号未乱
|
||||
- [ ] 链接、命令路径、文件名拼写正确
|
||||
- [ ] 中英文混用风格与现有章节一致
|
||||
- [ ] 没有把敏感信息（密码、token）写进文档
|
||||
- [ ] 涉及 AI 助手的提醒**具体到文件/命令**，不空泛
|
||||
- [ ] 改动反映在 `git status` 中**只**包含 `AGENTS.md`
|
||||
|
||||
### 同步与传播
|
||||
|
||||
- 复制到其他 stack 仓库时**只复制骨架**（章节标题），不要直接复制内容
|
||||
- 不同 stack 的"重要注意事项"差异很大，混用会导致 AI 误判
|
||||
- 如果有 fork/PR 流程，AGENTS.md 变更要在 PR 描述里说明理由
|
||||
|
||||
Reference in New Issue
Block a user