添加配置文件管理和完整文档系统

- 重构配置方式：使用 params.conf 替代命令行参数 - postinst 自动创建配置文件，升级时保护用户配置 - 初始化 llmdoc 文档系统（概述、架构、指南、参考） - 创建 README.md 和配置指南 - 提供完整的配置模板示例配置文件优势：升级安全、集中管理、易于维护
2025-12-19 09:20:33 +08:00
parent 1bafc36670
commit 9ff0daa938
14 changed files with 1083 additions and 19 deletions
--- a/llmdoc/architecture/cicd-architecture.md
+++ b/llmdoc/architecture/cicd-architecture.md
@@ -0,0 +1,83 @@
+# CI/CD 架构
+
+## 流水线概述
+
+P2Pool 构建系统使用 Gitea Actions 实现自动化构建、测试和发布流程。
+
+## 构建矩阵
+
+### 架构支持
+- amd64
+- arm64
+
+### 发行版本
+- Ubuntu
+- Alpine Linux
+
+### 构建组合
+- 总计 4 种构建变体：
+  1. amd64 + Ubuntu
+  2. amd64 + Alpine
+  3. arm64 + Ubuntu
+  4. arm64 + Alpine
+
+## 流水线触发条件
+
+### 自动触发
+- 推送到 `main` 和 `develop` 分支
+- 创建 Git 标签（发布版本）
+
+## 流水线阶段
+
+### 构建与测试阶段
+```yaml
+jobs:
+  build-and-test:
+    strategy:
+      matrix:
+        arch: [amd64, arm64]
+        distro: [ubuntu, alpine]
+
+    # 使用原生架构的 runner
+    runs-on: >-
+      ${{
+        matrix.arch == 'amd64' && 'ubuntu-latest-amd64' ||
+        'ubuntu-latest-arm64'
+      }}
+```
+
+### 关键步骤
+1. 设置 Docker Buildx
+2. 构建二进制文件
+3. 打包为 tar.gz
+4. 对于 Ubuntu：创建 Debian 包
+5. 上传构建产物
+
+### 发布阶段
+- 下载所有构建产物
+- 上传到 Gitea 通用包仓库
+- 上传 Debian 包
+- 创建发布版本
+- 附加下载链接
+
+## 性能特点
+
+### 原生架构构建
+- 比 QEMU 跨架构编译快 3-10 倍
+- 构建稳定性高
+- 需要专用的 amd64 和 arm64 runner
+
+### 编译并行度
+- amd64：使用一半 CPU 核心
+- arm64：使用全部 CPU 核心
+- 跨架构编译：限制为 2 个并行作业
+
+## 关键配置文件
+
+- [.gitea/workflows/ci.yaml](../../.gitea/workflows/ci.yaml)：主要 CI/CD 配置
+
+## 安全与性能平衡
+
+- 限制并行编译作业数
+- 使用原生架构 runner
+- 避免使用 QEMU 虚拟化
--- a/llmdoc/architecture/debian-packaging.md
+++ b/llmdoc/architecture/debian-packaging.md
@@ -0,0 +1,58 @@
+# Debian 包配置管理架构
+
+## 1. 配置文件管理机制
+
+### 配置文件位置和格式
+- **文件路径:** `/var/lib/p2pool/params.conf`
+- **文件权限:** `640` (所有者: `p2pool:p2pool`)
+- **格式:** 基于命令行参数的 key-value 配置文件
+
+### 配置文件生命周期
+
+#### 创建时机
+- **首次安装:** `postinst` 脚本自动创建示例配置文件
+- **升级场景:** 现有配置文件被完全保留，不会被覆盖
+
+#### 配置文件生成策略
+```bash
+# 配置文件初始化伪代码
+if [ ! -f /var/lib/p2pool/params.conf ]; then
+    cp /usr/share/p2pool/params.conf.example /var/lib/p2pool/params.conf
+    chown p2pool:p2pool /var/lib/p2pool/params.conf
+    chmod 640 /var/lib/p2pool/params.conf
+fi
+```
+
+### 配置加载机制
+- systemd 服务使用 `--params-file /var/lib/p2pool/params.conf` 加载配置
+- 配置文件支持所有原命令行参数
+- 配置文件优先级高于硬编码的默认值
+
+## 2. 安全与管理特性
+
+### 权限控制
+- 仅 `p2pool` 系统用户可读写配置文件
+- 组权限限制，防止非授权访问敏感配置
+- 文件权限 `640` 确保最小权限原则
+
+### 升级保护
+- 配置文件在包升级过程中保持不变
+- 新版本兼容旧配置文件格式
+- 升级后可通过比较 `params.conf.example` 检查新增配置项
+
+## 3. 配置示例
+
+```conf
+# /var/lib/p2pool/params.conf 示例
+wallet=YOUR_MONERO_WALLET_ADDRESS
+host=0.0.0.0
+rpc-port=3333
+log-level=1
+```
+
+## 4. 设计考量
+
+### 动机
+- 简化复杂的命令行参数管理
+- 提供更好的配置持久化方案
+- 增强系统配置的可读性和可维护性
--- a/llmdoc/architecture/docker-architecture.md
+++ b/llmdoc/architecture/docker-architecture.md
@@ -0,0 +1,93 @@
+# Docker 构建架构
+
+## 多阶段构建策略
+
+P2Pool 的 Docker 构建使用多阶段构建，确保最终镜像轻量且安全。
+
+### 构建阶段概览
+
+```
+┌─────────────────────────────────────────────────┐
+│ 阶段 1：基础镜像 (Alpine 3.21 / Ubuntu 24.04) │
+│ - 安装构建依赖：                               │
+│   git, cmake, gcc, g++, make                   │
+│   libuv-dev, libzmq-dev, libcurl-dev           │
+└─────────────────┬───────────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────────┐
+│ 阶段 2：构建                                   │
+│ 1. 从 GitHub 克隆 p2pool（使用 --recursive）   │
+│ 2. 检出指定的 P2POOL_VERSION 标签              │
+│ 3. CMake 配置：                                │
+│    - 发布构建                                  │
+│    - 禁用合并挖矿捐赠                          │
+│ 4. 使用 make 编译：                            │
+│    - 交叉编译：-j2                             │
+│    - amd64：-j$(nproc / 2)                     │
+│    - arm64：-j$(nproc)                         │
+└─────────────────┬───────────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────────┐
+│ 阶段 3：提取 (scratch 镜像)                    │
+│ - 将二进制文件复制到 /linux_${TARGETARCH}/     │
+│ - 启用 Docker buildx 本地文件提取              │
+└──────────────────────────────────────────────────┘
+```
+
+## 关键构建参数
+
+### 版本控制
+- `P2POOL_VERSION`：指定上游 p2pool 版本
+- 使用 `--build-arg` 传递版本
+
+### 编译配置
+- `-DWITH_MERGE_MINING_DONATION=OFF`：禁用合并挖矿捐赠
+- 不同架构的编译并行度控制
+
+## 镜像变体
+
+### Alpine 镜像 (推荐)
+- 基于 Alpine Linux
+- 镜像体积小
+- 安全性高
+- 文件：`docker/Dockerfile.alpine`
+
+### Ubuntu 镜像
+- 基于 Ubuntu LTS
+- 更广泛的系统兼容性
+- 文件：`docker/Dockerfile.ubuntu`
+
+## 构建命令示例
+
+```bash
+# Alpine 构建（推荐）
+docker buildx build --pull \
+  --platform linux/amd64 \
+  --build-arg P2POOL_VERSION=v4.9.1 \
+  --output type=local,dest=./output \
+  -f docker/Dockerfile.alpine .
+
+# 多架构构建
+docker buildx build --pull \
+  --platform linux/amd64,linux/arm64 \
+  --build-arg P2POOL_VERSION=v4.9.1 \
+  --output type=local,dest=./output \
+  -f docker/Dockerfile.alpine .
+```
+
+## 性能优化策略
+
+### 并行度控制
+- amd64：`$(nproc) / 2`（减少资源竞争）
+- arm64：`$(nproc)`（充分利用资源）
+
+### 缓存优化
+- 使用多阶段构建减少最终镜像大小
+- 利用 Docker 构建缓存
+
+## 注意事项
+
+- 需要 Docker Buildx 支持
+- 构建需要互联网连接
+- 克隆上游仓库需要 `--recursive` 参数
+- 编译过程禁用合并挖矿捐赠功能