添加 Nezha Agent 管理功能和完整文档系统
- 新增 Nezha Agent client_secret 更新 playbook(两种实现方案) - 建立三层文档架构:docs/(用户文档)、examples/(配置示例)、llmdoc/(技术文档) - 添加项目主 README.md 和配置示例文件 - 初始化 .gitignore 保护敏感信息
This commit is contained in:
65
llmdoc/reference/coding-conventions.md
Normal file
65
llmdoc/reference/coding-conventions.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Ansible 与 YAML 编码规范
|
||||
|
||||
## YAML 格式规范
|
||||
|
||||
### 基本格式
|
||||
- 使用 `---` 作为 YAML 文件开头
|
||||
- 缩进严格使用 **2 个空格**
|
||||
- 禁止使用制表符 `\t`
|
||||
- 保持每行末尾无多余空白
|
||||
|
||||
### 文件命名
|
||||
- Playbook 文件使用 `snake_case`
|
||||
- 文件扩展名为 `.yml`
|
||||
|
||||
## Ansible 编码规范
|
||||
|
||||
### 变量命名
|
||||
- 变量名使用 `snake_case`
|
||||
- 布尔变量使用肯定语气命名,如 `enable_feature`
|
||||
- 使用有意义的、描述性的变量名
|
||||
|
||||
### Playbook 结构
|
||||
- 每个 Playbook 应包含:
|
||||
1. `name`: 描述性标题
|
||||
2. `hosts`: 目标主机
|
||||
3. `vars`: 变量定义区
|
||||
4. `tasks`: 任务列表
|
||||
5. 可选 `handlers`: 触发的服务重启/重载任务
|
||||
|
||||
### 任务编写
|
||||
- 每个任务使用 `name` 描述具体操作
|
||||
- 优先使用 `ansible.builtin` 模块
|
||||
- 添加 `when` 条件控制任务执行
|
||||
- 使用 `register` 捕获任务输出
|
||||
- 通过 `changed_when: false` 控制任务变更状态
|
||||
|
||||
### 注释规范
|
||||
- 使用 `#` 添加注释
|
||||
- 注释应解释"为什么",而非"做什么"
|
||||
- 在复杂配置处添加必要的注释说明
|
||||
|
||||
### 安全与最佳实践
|
||||
- 使用 `become: yes` 控制权限提升
|
||||
- 避免硬编码敏感信息
|
||||
- 使用 `no_log: true` 隐藏敏感输出
|
||||
- 合理使用 `backup: yes` 保护现有配置
|
||||
|
||||
## 示例代码风格
|
||||
```yaml
|
||||
---
|
||||
- name: 配置服务
|
||||
hosts: servers
|
||||
become: yes
|
||||
|
||||
vars:
|
||||
service_port: 8080
|
||||
enable_monitoring: true
|
||||
|
||||
tasks:
|
||||
- name: 部署服务配置
|
||||
ansible.builtin.template:
|
||||
src: config.j2
|
||||
dest: /etc/service/config.yml
|
||||
when: enable_monitoring
|
||||
```
|
||||
Reference in New Issue
Block a user