添加 Nezha Agent 管理功能和完整文档系统

- 新增 Nezha Agent client_secret 更新 playbook（两种实现方案） - 建立三层文档架构：docs/（用户文档）、examples/（配置示例）、llmdoc/（技术文档） - 添加项目主 README.md 和配置示例文件 - 初始化 .gitignore 保护敏感信息
2025-12-16 10:52:38 +08:00
parent f08326fec3
commit 167fad20eb
32 changed files with 2090 additions and 0 deletions
--- a/llmdoc/reference/ansible-modules-used.md
+++ b/llmdoc/reference/ansible-modules-used.md
@@ -0,0 +1,47 @@
+# Ansible 模块参考
+
+## 核心模块列表
+
+### 1. ansible.builtin.set_fact
+- **用途**：动态构建和设置变量
+- **示例**：`ansible.builtin.set_fact: install_command="..."`
+
+### 2. ansible.builtin.debug
+- **用途**：输出调试信息和变量
+- **关键参数**：
+  - `msg`：直接打印消息
+  - `var`：打印变量值
+
+### 3. ansible.builtin.get_url
+- **用途**：从远程 URL 下载文件
+- **关键参数**：
+  - `url`：文件源地址
+  - `dest`：目标路径
+  - `mode`：文件权限
+
+### 4. ansible.builtin.shell
+- **用途**：执行复杂的 Shell 命令
+- **注意事项**：
+  - 比 `command` 模块更灵活
+  - 支持管道和重定向
+
+### 5. ansible.builtin.file
+- **用途**：文件和目录管理
+- **常用状态**：
+  - `present`：确保文件存在
+  - `absent`：确保文件不存在
+  - `directory`：确保目录存在
+
+## 使用场景映射
+
+- 文件下载：`get_url`
+- 动态参数：`set_fact`
+- 命令执行：`shell`
+- 日志记录：`debug`
+- 文件清理：`file`
+
+## 最佳实践提示
+
+1. 优先使用专用模块
+2. 谨慎使用 `shell` 模块
+3. 始终关注安全性和幂等性
--- a/llmdoc/reference/coding-conventions.md
+++ b/llmdoc/reference/coding-conventions.md
@@ -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
+```
--- a/llmdoc/reference/git-conventions.md
+++ b/llmdoc/reference/git-conventions.md
@@ -0,0 +1,31 @@
+# Git 约定参考
+
+## 分支策略
+
+- **主分支:** `main`
+- **分支管理:** 直接在 `main` 分支上提交更改
+
+## Commit Message 规范
+
+### 消息风格
+- 使用简体中文
+- 简洁描述更改内容
+- 消息格式示例：
+  - `添加执行参数`
+  - `添加`
+
+### Commit 模式
+- 提交频率：较低，主要捕捉重要功能和变更
+- 提交者：单一开发者（Wang Defa）
+
+## 版本管理
+
+- **当前版本管理方式:** 简单、直接
+- **特点:** 轻量级提交，无复杂的分支管理
+- **建议:** 考虑引入更结构化的版本控制流程
+
+## 最佳实践建议
+
+1. 保持 Commit Message 简洁明了
+2. 每次提交聚焦于单一功能或修复
+3. 考虑添加更详细的变更描述
--- a/llmdoc/reference/jinja2-parameter-patterns.md
+++ b/llmdoc/reference/jinja2-parameter-patterns.md
@@ -0,0 +1,34 @@
+# Jinja2 参数构建模式参考
+
+## 1. 条件参数生成基本模式
+
+### 布尔开关模式
+```yaml
+{{ '--flag' if boolean_var else '' }}
+```
+
+### 带值参数模式
+```yaml
+{{ '--param ' + value if condition else '' }}
+```
+
+## 2. 复合条件示例
+
+```yaml
+{{ '--cc-tls' if enable_cc and enable_cc_tls else '' }}
+```
+
+## 3. 参数构建最佳实践
+
+- 使用三元运算符 `if-else`
+- 避免使用复杂的嵌套条件
+- 保持参数生成逻辑简洁明了
+
+## 4. 性能与可读性
+
+- Jinja2 条件语法开销极小
+- 比传统编程逻辑更加声明式和直观
+
+## 5. 源代码参考
+
+- `xxxigcc_install.yaml:25-34`: 动态参数构建的实际实现
--- a/llmdoc/reference/journald-parameters.md
+++ b/llmdoc/reference/journald-parameters.md
@@ -0,0 +1,53 @@
+# Journald 配置参数参考
+
+## 核心摘要
+
+本文档提供了 systemd-journald 日志配置的详细参数参考，旨在帮助开发者和系统管理员精确控制日志行为。
+
+## 参数列表
+
+### 空间管理参数
+
+1. **SystemMaxUse**
+   - **描述：** 日志总体使用空间上限
+   - **默认值：** "500M"
+   - **类型：** 存储大小（字节/K/M/G）
+   - **作用：** 限制所有日志条目占用的总磁盘空间
+
+2. **SystemMaxFileSize**
+   - **描述：** 单个日志文件大小限制
+   - **默认值：** "100M"
+   - **类型：** 存储大小（字节/K/M/G）
+   - **作用：** 控制单个日志文件的最大尺寸
+
+### 保留和过期策略
+
+3. **MaxRetentionSec**
+   - **描述：** 日志保留时间
+   - **默认值：** "7day"
+   - **类型：** 时间间隔（秒/分钟/小时/天）
+   - **作用：** 确定日志保留的最长时间
+
+### 速率控制参数
+
+4. **RateLimitIntervalSec**
+   - **描述：** 日志速率限制时间间隔
+   - **默认值：** "30s"
+   - **类型：** 时间间隔
+   - **作用：** 定义速率限制的时间窗口
+
+5. **RateLimitBurst**
+   - **描述：** 日志突发速率限制
+   - **默认值：** "10000"
+   - **类型：** 整数
+   - **作用：** 在指定时间间隔内允许的最大日志条目数
+
+## 源代码引用
+
+- **主要配置文件：** `journald_configure.yml`
+- **架构文档：** `/llmdoc/architecture/journald-configuration-flow.md`
+
+## 相关架构文档
+
+- [Journald 配置流程架构](/llmdoc/architecture/journald-configuration-flow.md)
+- [Journald 配置指南](/llmdoc/guides/how-to-configure-journald.md)
--- a/llmdoc/reference/security-checklist.md
+++ b/llmdoc/reference/security-checklist.md
@@ -0,0 +1,25 @@
+# 安全检查清单
+
+## 1. 权限管理检查
+
+### Sudo 和权限提升
+- [ ] 所有 Playbook 是否正确使用 `become: yes`
+- [ ] 权限提升是否遵循最小权限原则
+- [ ] 是否有不必要的全局 root 权限使用
+
+## 2. 脚本下载安全
+- [ ] 所有脚本下载是否启用 `validate_certs: yes`
+- [ ] 下载脚本权限是否正确设置（`mode: '0755'`）
+- [ ] 下载源是否可信且使用 HTTPS
+
+## 3. 日志安全配置
+- [ ] 日志总大小限制是否合理（默认 500M）
+- [ ] 单个日志文件大小限制（默认 100M）
+- [ ] 日志保留期限设置（默认 7 天）
+- [ ] 日志速率限制是否正确配置
+
+## 4. 常规安全审计
+- [ ] 定期检查并更新安全配置
+- [ ] 审核所有自动化脚本
+- [ ] 检查证书和加密设置
+- [ ] 监控异常日志和访问行为
--- a/llmdoc/reference/xxxigcc-parameters.md
+++ b/llmdoc/reference/xxxigcc-parameters.md
@@ -0,0 +1,31 @@
+# XXXigCC 部署参数参考
+
+## 1. 核心摘要
+XXXigCC 的部署采用高度灵活的参数配置机制，支持多种功能开关和高级配置选项。
+
+## 2. 参数分类
+
+### 必填参数
+| 参数名称 | 描述 | 示例 |
+|---------|------|------|
+| `pool_url` | 资源池 URL | `http://pool.example.com` |
+| `cc_url` | 控制中心 URL | `https://control.center` |
+| `cc_token` | 控制中心访问令牌 | `secret-token-123` |
+
+### 可选布尔参数
+| 参数名称 | 默认值 | 功能描述 |
+|---------|--------|----------|
+| `enable_cc` | true | 启用控制中心功能 |
+| `enable_tls` | true | 启用传输层安全 |
+| `enable_cc_tls` | true | 控制中心启用 TLS |
+| `enable_keepalive` | true | 维持长连接 |
+| `enable_1gb_pages` | true | 使用大页内存 |
+
+## 3. 来源真相
+- 主要代码：`xxxigcc_install.yaml` - 定义参数和安装逻辑
+- 安装脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/install.deb.sh`
+- 卸载脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/uninstall.sh`
+
+## 4. 外部文档
+- 功能规范文档：待补充
+- 性能配置指南：待补充