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

- 重构配置方式：使用 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` 参数
+- 编译过程禁用合并挖矿捐赠功能
--- a/llmdoc/guides/debian-package.md
+++ b/llmdoc/guides/debian-package.md
@@ -0,0 +1,135 @@
+# Debian 包安装与配置指南
+
+## 安装步骤
+
+### 添加 Gitea 包仓库
+
+```bash
+# 导入 Gitea 仓库密钥
+sudo curl https://GITEA_URL/api/packages/OWNER/debian/repository.key \
+  -o /etc/apt/keyrings/gitea-OWNER.asc
+
+# 添加仓库源（以 Debian 12 为例）
+echo "deb [signed-by=/etc/apt/keyrings/gitea-OWNER.asc] \
+  https://GITEA_URL/api/packages/OWNER/debian bookworm main" | \
+  sudo tee /etc/apt/sources.list.d/OWNER.list
+
+# 更新包列表并安装
+sudo apt-get update
+sudo apt-get install p2pool
+```
+
+## 配置 P2Pool
+
+### 编辑配置文件
+
+P2Pool 使用配置文件 `/var/lib/p2pool/params.conf` 来管理所有设置。安装后会自动创建示例配置文件。
+
+```bash
+# 编辑配置文件
+sudo nano /var/lib/p2pool/params.conf
+```
+
+配置文件示例：
+```conf
+# P2Pool Configuration File
+
+# Monero node connection
+host = 127.0.0.1
+rpc-port = 18081
+zmq-port = 18083
+
+# Your Monero wallet address (REQUIRED)
+wallet = YOUR_MONERO_WALLET_ADDRESS
+
+# P2P settings
+p2p = 0.0.0.0:37889
+
+# API settings
+data-api = /var/lib/p2pool/data-api
+local-api = true
+
+# Logging
+log-file = /var/log/p2pool/p2pool.log
+loglevel = 3
+
+# Mining mode (uncomment to enable mini sidechain)
+# mini = true
+
+# Stratum server (for miners to connect)
+# stratum = 0.0.0.0:3333
+```
+
+### 关键配置参数
+
+- `host`：Monero 节点的 IP 地址
+- `rpc-port`：Monero 节点的 RPC 端口
+- `zmq-port`：Monero 节点的 ZMQ 端口
+- `wallet`：**必需** - 您的 Monero 钱包地址
+- `mini`：启用 mini 侧链（适合算力较小的矿工）
+- `stratum`：Stratum 服务器地址，供矿机连接
+- `loglevel`：日志级别（0-6，3 为默认值）
+
+### 配置文件的优势
+
+- ✅ **版本升级安全**：`params.conf` 在 `apt upgrade` 时不会被覆盖
+- ✅ **易于管理**：所有配置集中在一个文件中
+- ✅ **支持注释**：可以添加说明和注释
+- ✅ **无需修改 systemd**：避免编辑系统服务文件
+
+## 启动和管理服务
+
+```bash
+# 启用服务，设置开机自启
+sudo systemctl enable p2pool.service
+
+# 启动服务
+sudo systemctl start p2pool.service
+
+# 查看服务状态
+sudo systemctl status p2pool.service
+
+# 查看实时日志
+sudo journalctl -u p2pool -f
+```
+
+## 目录结构
+
+- `/opt/p2pool/p2pool`：P2Pool 二进制文件
+- `/var/lib/p2pool/`：数据目录
+- `/var/log/p2pool/`：日志目录
+
+## 安全建议
+
+- 使用专用钱包地址
+- 限制 Stratum 端口的网络访问
+- 定期更新 p2pool 版本
+
+## 故障排查
+
+### 常见错误
+
+- RPC 端口配置不正确
+- 钱包地址无效
+- 网络连接问题
+
+### 检查日志
+
+```bash
+# 查看完整日志
+sudo cat /var/log/p2pool/p2pool.log
+
+# 查看最近错误
+sudo journalctl -u p2pool -n 50 --no-pager
+```
+
+## 版本管理
+
+```bash
+# 查看当前版本
+/opt/p2pool/p2pool --version
+
+# 检查可用更新
+sudo apt-get update
+sudo apt-cache policy p2pool
+```
--- a/llmdoc/guides/local-build.md
+++ b/llmdoc/guides/local-build.md
@@ -0,0 +1,88 @@
+# 本地构建指南
+
+## 准备工作
+
+### 系统依赖
+- Docker
+- Docker Buildx
+- Git
+
+### 安装 Docker Buildx
+
+```bash
+# 启用 QEMU（支持多平台构建）
+docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+
+# 创建 buildx builder
+docker buildx create --use --name p2pool_builder --driver docker-container
+docker buildx inspect --bootstrap
+```
+
+## 构建二进制包
+
+### Alpine 构建（推荐）
+
+```bash
+# 构建单一架构
+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 .
+```
+
+### Ubuntu 构建
+
+```bash
+docker buildx build --pull \
+  --platform linux/amd64 \
+  --build-arg P2POOL_VERSION=v4.9.1 \
+  --output type=local,dest=./output \
+  -f docker/Dockerfile.ubuntu .
+```
+
+## 构建 Debian 包
+
+```bash
+# 打包二进制文件
+TARGZ="p2pool-amd64-ubuntu-v4.12.tar.gz"
+tar -czf "${TARGZ}" -C ./output/linux_amd64 .
+
+# 生成 Debian 包
+./debian/build-deb.sh amd64 v4.12 "${TARGZ}"
+```
+
+## 常见问题排查
+
+### 调整编译并行度
+
+修改 Dockerfile 中的 `MAKE_JOBS` 变量：
+
+```dockerfile
+# 使用全部 CPU 核心（amd64）
+elif [ "$TARGETARCH" = "amd64" ]; then \
+    MAKE_JOBS="-j$(nproc)";
+
+# 或使用固定作业数
+elif [ "$TARGETARCH" = "amd64" ]; then \
+    MAKE_JOBS="-j4";
+```
+
+### 网络和依赖问题
+
+- 确保 Docker 可以访问互联网
+- 检查 Git 子模块是否正确初始化
+- 验证 CMake 和编译器版本兼容性
+
+## 性能提示
+
+- 使用 SSD 提高构建速度
+- 保持 Docker 镜像和依赖更新
+- 对于大型项目，考虑使用构建缓存
--- a/llmdoc/index.md
+++ b/llmdoc/index.md
@@ -0,0 +1,12 @@
+# P2Pool Debian 打包与配置系统文档
+
+## 文档导航
+
+### 总览
+- [架构：Debian 包管理](/llmdoc/architecture/debian-packaging.md)
+
+### 指南
+- [Debian 包安装与配置](/llmdoc/guides/debian-package.md)
+
+### 参考资料
+- 待添加
--- a/llmdoc/overview/project-overview.md
+++ b/llmdoc/overview/project-overview.md
@@ -0,0 +1,45 @@
+# 项目概述：P2Pool Docker 构建基础设施
+
+## 项目背景
+
+P2Pool 是一个去中心化的 Monero 矿池，本项目旨在提供一个标准化、可靠的构建和打包基础设施。
+
+## 主要目标
+
+1. 自动化构建 p2pool 二进制包
+2. 支持多架构（amd64, arm64）
+3. 生成 Debian 和通用包
+4. 禁用合并挖矿捐赠功能
+
+## 构建输出
+
+- **二进制包**：
+  - amd64 架构
+  - arm64 架构
+- **包格式**：
+  - tar.gz 压缩包
+  - Debian 包（.deb）
+- **构建基础镜像**：
+  - Alpine Linux (推荐)
+  - Ubuntu LTS
+
+## 关键特性
+
+- 使用 Docker 多阶段构建
+- 通过 Gitea Actions 自动化 CI/CD
+- 支持版本化构建
+- 原生架构构建，性能优化
+- 自动包发布到 Gitea 包仓库
+
+## 版本管理
+
+- 直接从 [SChernykh/p2pool](https://github.com/SChernykh/p2pool) 上游仓库构建
+- 通过 `P2POOL_VERSION` 环境变量控制构建版本
+- 使用 Git 标签管理版本发布
+
+## 使用限制
+
+- 不包含 p2pool 源代码
+- 构建时需要互联网连接
+- 依赖 Docker Buildx
+- 需要配置钱包地址才能运行服务
--- a/llmdoc/reference/coding-conventions.md
+++ b/llmdoc/reference/coding-conventions.md
@@ -0,0 +1,59 @@
+# 编码规范
+
+## Shell 脚本规范
+
+### 基本原则
+- 使用 `#!/bin/sh` 作为脚本头
+- 遵循 POSIX shell 标准
+- 避免使用 Bash 特定语法
+
+### 缩进与格式
+- 使用 4 个空格缩进
+- 每个代码块使用一致的缩进
+- 长行使用 `\` 换行
+
+### 变量使用
+- 使用双引号包裹变量：`"$VARIABLE"`
+- 避免未定义变量
+- 使用 `${VARIABLE:-default}` 设置默认值
+
+### 示例
+
+```sh
+#!/bin/sh
+set -eu
+
+# 变量定义
+P2POOL_VERSION="${1:-v4.9.1}"
+OUTPUT_DIR="${2:-./output}"
+
+# 函数定义
+build_p2pool() {
+    local arch="$1"
+    local distro="$2"
+
+    docker buildx build --pull \
+        --platform "linux/${arch}" \
+        --build-arg "P2POOL_VERSION=${P2POOL_VERSION}" \
+        --output "type=local,dest=${OUTPUT_DIR}" \
+        -f "docker/Dockerfile.${distro}" .
+}
+
+# 主逻辑
+main() {
+    build_p2pool "amd64" "alpine"
+}
+
+main "$@"
+```
+
+## Docker 文件规范
+- 遵循多阶段构建
+- 尽量减少镜像层数
+- 使用多架构构建
+- 避免在构建过程中下载可变内容
+
+## Git 提交规范
+- 使用清晰、简洁的提交信息
+- 提交信息应描述**为什么**做这个改动
+- 使用动词开头：添加(Add)、修复(Fix)、优化(Improve)等
--- a/llmdoc/reference/git-conventions.md
+++ b/llmdoc/reference/git-conventions.md
@@ -0,0 +1,79 @@
+# Git 协作规范
+
+## 分支管理
+
+### 主分支
+- `main`: 稳定版本
+- `develop`: 开发分支
+
+### 开发流程
+1. 从 `develop` 创建功能分支
+2. 功能分支命名规范：
+   - `feature/` 前缀表示新功能
+   - `bugfix/` 前缀表示 bug 修复
+   - `docs/` 前缀表示文档更新
+
+### 示例分支创建
+```bash
+# 从 develop 创建功能分支
+git checkout develop
+git pull origin develop
+git checkout -b feature/add-architecture-docs
+```
+
+## 提交规范
+
+### 提交信息格式
+```
+<类型>: <简要描述>
+
+[可选的详细说明]
+
+[关联的 issue 或 PR]
+```
+
+### 类型定义
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码风格调整
+- `refactor`: 重构
+- `test`: 测试相关
+- `build`: 构建系统或外部依赖变更
+- `ci`: CI 配置变更
+
+### 提交示例
+```bash
+docs: 添加 p2pool 构建文档系统
+
+- 创建 llmdoc 目录结构
+- 添加项目概述文档
+- 编写编码和 Git 规范文档
+
+关联 Issue: #123
+```
+
+## 代码审查
+
+### 合并请求(PR)规范
+- 所有 PR 必须从功能分支提交到 `develop`
+- PR 标题应简洁描述变更
+- PR 描述必须包含：
+  1. 变更的目的
+  2. 具体实现
+  3. 测试方法
+- 至少需要一个审查者批准
+
+## 版本标签
+
+### 版本命名
+- 使用语义化版本 (Semantic Versioning)
+- 格式：`vMAJOR.MINOR.PATCH`
+- 示例：`v4.12.0`
+
+### 发布流程
+```bash
+# 创建版本标签
+git tag v4.12.0
+git push origin v4.12.0
+```