简化 Debian 发布流程并添加项目文档系统

- 将 Debian 包仓库从 bookworm/trixie 双发行版改为通用 stable 仓库
- 新增完整的 llmdoc 文档系统，包含架构、指南和参考文档
- 更新 README.md 和部署指南以反映新的仓库配置
- 添加 .gitignore 文件

llmdoc/guides/how-to-build-debian-package.md

@@ -0,0 +1,42 @@
+# 如何构建 Debian 包
+
+## 先决条件
+
+1. **环境准备**
+   - 已安装 `build-essential`
+   - 已安装 `dpkg-dev`
+   - 准备源代码 tar.gz 文件
+
+2. **构建参数**
+   - 架构：`amd64` 或 `arm64`
+   - 版本号：例如 `3.4.8-xg1`
+   - 源代码压缩包：`xxxigcc-proxy-amd64-ubuntu-3.4.8-xg1.tar.gz`
+
+## 构建步骤
+
+1. **进入项目根目录**
+   ```bash
+   cd /path/to/xxxigcc-proxy
+   ```
+
+2. **执行构建脚本**
+   ```bash
+   bash debian/build-deb.sh amd64 3.4.8-xg1 xxxigcc-proxy-amd64-ubuntu-3.4.8-xg1.tar.gz
+   ```
+
+3. **验证构建结果**
+   - 检查生成的 `.deb` 文件
+   - 使用 `dpkg -I` 查看包信息
+
+## 常见问题排查
+
+- 确保源代码 tar.gz 文件存在且解压正确
+- 检查架构是否匹配
+- 验证依赖项是否满足
+- 查看构建日志定位错误
+
+## 安全提示
+
+- 仅使用可信的源代码
+- 在隔离环境中构建（如 Docker）
+- 验证源代码完整性

llmdoc/guides/how-to-build-docker-images.md

@@ -0,0 +1,55 @@
+# 如何构建 Docker 镜像
+
+## 前提条件
+
+1. 安装 Docker BuildX
+2. 启用 Docker BuildKit
+   ```bash
+   export DOCKER_BUILDKIT=1
+   export BUILDX_NO_DEFAULT_ATTESTATIONS=1
+   ```
+
+## 本地构建步骤
+
+### 1. 创建 BuildX 实例
+```bash
+docker buildx create --name multiarch --driver docker-container
+docker buildx use multiarch
+docker buildx inspect --bootstrap
+```
+
+### 2. 构建多架构镜像
+```bash
+# 构建 Ubuntu 版本
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -f docker/Dockerfile.ubuntu \
+  -t xxxigcc-proxy:latest \
+  --push .
+
+# 构建 Alpine 版本
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -f docker/Dockerfile.alpine \
+  -t xxxigcc-proxy:alpine \
+  --push .
+```
+
+## 添加新的架构/发行版
+
+### 修改步骤
+1. 更新 Dockerfile
+2. 调整 `.gitea/workflows/ci.yaml`
+3. 更新 `init.sh` 中的兼容性脚本
+
+### 注意事项
+- 确保所有依赖支持新架构
+- 验证交叉编译兼容性
+- 更新 CI/CD 矩阵配置
+
+## 常见问题排查
+
+### 构建失败
+- 检查 BuildX 实例状态
+- 验证依赖工具链
+- 查看详细构建日志

llmdoc/guides/how-to-configure.md

@@ -0,0 +1,57 @@
+# XXXigCC Proxy 配置指南
+
+## 配置文件基础
+
+配置文件使用 JSON 格式，位置取决于安装方式：
+- Debian 包：`/etc/xxxigcc-proxy/config.json`
+- 二进制版本：`./config.json`
+
+## 主要配置选项
+
+### 1. 网络监听配置
+
+```json
+{
+    "bind": "0.0.0.0:3333"  // 监听所有网络接口，端口3333
+}
+```
+
+### 2. 矿池配置示例
+
+```json
+{
+    "pools": [
+        {
+            "url": "pool.example.com:3333",
+            "user": "your_wallet_address",
+            "pass": "x"
+        }
+    ]
+}
+```
+
+### 3. 日志配置
+
+```json
+{
+    "log-file": "/var/log/xxxigcc-proxy/proxy.log",
+    "access-log-file": "/var/log/xxxigcc-proxy/access.log"
+}
+```
+
+## 最佳实践
+
+1. 使用强密码或 token
+2. 限制网络访问
+3. 定期轮换日志
+4. 监控系统资源使用情况
+
+## 配置验证
+
+```bash
+# 检查配置语法
+xxxigcc-proxy --config=config.json --test
+
+# 查看当前配置
+xxxigcc-proxy --config=config.json --print-config
+```

llmdoc/guides/how-to-deploy.md

@@ -0,0 +1,59 @@
+# XXXigCC Proxy 部署指南
+
+## 部署方式概览
+
+XXXigCC Proxy 支持三种部署方式：Debian 仓库、二进制包、Docker。
+
+### 1. Debian 仓库安装（推荐）
+
+```bash
+# 添加仓库密钥
+sudo curl https://gitea.bcde.io/api/packages/wangdefa/debian/repository.key -o /etc/apt/keyrings/gitea-wangdefa.asc
+
+# 配置仓库（通用稳定版，支持所有 Debian/Ubuntu 发行版）
+echo "deb [signed-by=/etc/apt/keyrings/gitea-wangdefa.asc] https://gitea.bcde.io/api/packages/wangdefa/debian stable main" | sudo tee -a /etc/apt/sources.list.d/wangdefa.list
+
+# 安装
+sudo apt-get update
+sudo apt-get install xxxigcc-proxy
+```
+
+### 2. 二进制包部署
+
+```bash
+# 下载最新版本
+wget https://gitea.bcde.io/api/packages/wangdefa/generic/xxxigcc-proxy/3.4.6-xg1/xxxigcc-proxy-amd64-ubuntu-3.4.6-xg1.tar.gz
+
+# 解压
+tar -xzf xxxigcc-proxy-amd64-ubuntu-3.4.6-xg1.tar.gz
+
+# 运行
+./xxxigcc-proxy --config=config.json
+```
+
+### 3. Docker 部署（社区建议）
+
+*注意：Docker 部署暂未正式支持，需要社区贡献*
+
+## 部署后管理
+
+```bash
+# 编辑配置
+sudo nano /etc/xxxigcc-proxy/config.json
+
+# 重启服务
+sudo systemctl restart xxxigcc-proxy
+
+# 查看服务状态
+sudo systemctl status xxxigcc-proxy
+
+# 查看实时日志
+sudo journalctl -u xxxigcc-proxy -f
+```
+
+## 注意事项
+
+- 默认监听地址：`0.0.0.0:3333`
+- 配置文件路径：
+  - Debian 包：`/etc/xxxigcc-proxy/config.json`
+  - 二进制版本：`./config.json`

llmdoc/guides/how-to-modify-cicd-workflow.md

@@ -0,0 +1,73 @@
+# 如何修改 CI/CD 工作流
+
+## 1. 关键文件位置
+- 工作流定义：`.gitea/workflows/ci.yaml`
+- Debian 打包脚本：`debian/build-deb.sh`
+
+## 2. 修改构建作业
+
+### 2.1 添加新构建步骤
+在 `build-and-test` 作业中添加步骤：
+```yaml
+- name: 新构建步骤
+  run: |
+    # 添加新的构建或测试逻辑
+```
+
+### 2.2 调整构建矩阵
+修改 `strategy.matrix` 部分：
+```yaml
+strategy:
+  matrix:
+    arch: [amd64, arm64, riscv64]  # 添加新架构
+    distro: [ubuntu, alpine, fedora]  # 添加新发行版
+```
+
+## 3. 修改发布作业
+
+### 3.1 调整上传逻辑
+在 `release` 作业中修改上传代码：
+```yaml
+- name: 上传到新的包管理器
+  run: |
+    # 添加新的上传目标
+```
+
+### 3.2 定制 Release 说明
+修改 Python 代码生成 Release 说明：
+```python
+# 在生成 Release 说明的代码块中添加自定义逻辑
+```
+
+## 4. Debian 打包定制
+
+### 4.1 修改打包脚本
+编辑 `debian/build-deb.sh`：
+- 添加新的架构支持
+- 调整文件权限
+- 修改 systemd 服务配置
+
+### 4.2 更新控制文件模板
+修改 `debian/control.template`：
+- 更新依赖关系
+- 调整包元数据
+
+## 5. 测试工作流变更
+
+### 5.1 本地测试
+```bash
+# 使用 act 或 gitea-act 在本地测试工作流
+act -j build-and-test
+```
+
+### 5.2 分支测试
+1. 创建新分支
+2. 推送修改
+3. 检查 CI 构建结果
+
+## 6. 最佳实践
+
+- 保持向后兼容性
+- 详细记录工作流变更
+- 增量测试新功能
+- 遵循现有的构建和打包模式

llmdoc/guides/how-to-modify-source-code.md

@@ -0,0 +1,91 @@
+# 如何修改源代码
+
+## 1. 准备工作
+
+在开始修改源代码之前，请确保：
+- 已克隆原始项目仓库
+- 安装必要的开发工具（sed, git）
+- 了解项目的基本架构
+
+## 2. 修改步骤
+
+### 2.1 项目重命名
+1. 编辑 `CMakeLists.txt`
+2. 使用 `sed` 命令替换项目名称：
+```bash
+sed -i 's/project(xmrigcc-proxy)/project(xxxigcc-proxy)/' CMakeLists.txt
+```
+
+### 2.2 禁用捐赠功能
+1. 修改以下文件：
+   - `src/donate.h`
+   - `src/net/strategies/DonateStrategy.cpp`
+   - `src/core/config/Config_platform.h`
+   - `src/config.json`
+
+2. 使用 `sed` 命令设置捐赠级别为 0：
+```bash
+sed -i 's/kDefaultDonateLevel = 2/kDefaultDonateLevel = 0/' src/donate.h
+sed -i 's/donate-level",      1/donate-level",      0/' src/core/config/Config_platform.h
+```
+
+3. 重定向捐赠服务器地址：
+```bash
+sed -i 's/donate.graef.in/127.0.0.1/' src/net/strategies/DonateStrategy.cpp
+sed -i 's/87.106.163.52/127.0.0.1/' src/net/strategies/DonateStrategy.cpp
+```
+
+### 2.3 版本信息定制
+1. 编辑 `src/version.h`
+2. 替换版本字符串：
+```bash
+sed -i 's/xmrigcc/xxxigcc/' src/version.h
+sed -i 's/XMRigCC/XXXigCC/' src/version.h
+```
+
+### 2.4 启用详细日志
+1. 编辑 `src/config.json`
+2. 设置 verbose 为 true：
+```bash
+sed -i 's/"verbose": false/"verbose": true/' src/config.json
+```
+
+## 3. 测试修改
+
+1. 构建项目
+```bash
+mkdir build && cd build
+cmake ..
+make
+```
+
+2. 运行单元测试
+```bash
+make test
+```
+
+3. 手动测试程序的基本功能
+
+## 4. 常见问题排查
+
+### 4.1 sed 命令替换失败
+- 检查目标字符串是否完全匹配
+- 确保文件路径正确
+- 使用 `-i.bak` 创建备份文件，方便回滚
+
+### 4.2 构建失败
+- 检查 CMake 配置
+- 验证所有依赖库已安装
+- 查看完整的编译日志
+
+### 4.3 功能异常
+- 对比修改前后的配置文件
+- 检查 verbose 日志
+- 逐步还原修改，定位问题
+
+## 5. 最佳实践
+
+- 始终在版本控制系统中工作
+- 为每次重大修改创建单独的分支
+- 保留原始项目的基本架构和功能
+- 充分测试每一个修改

llmdoc/guides/how-to-modify-systemd-service.md

@@ -0,0 +1,51 @@
+# 如何修改 Systemd 服务配置
+
+## 服务文件位置
+
+`/lib/systemd/system/xxxigcc-proxy.service`
+
+## 配置修改步骤
+
+1. **编辑服务文件**
+   ```bash
+   sudo nano /lib/systemd/system/xxxigcc-proxy.service
+   ```
+
+2. **常见修改场景**
+
+### A. 更改启动参数
+修改 `ExecStart` 行：
+```
+ExecStart=/opt/xxxigcc-proxy/xxxigcc-proxy --config=/etc/xxxigcc-proxy/config.json [新参数]
+```
+
+### B. 调整资源限制
+修改 `LimitNOFILE` 和 `LimitNPROC`：
+```
+LimitNOFILE=100000   # 增加文件描述符限制
+LimitNPROC=8192      # 增加最大进程数
+```
+
+### C. 安全性增强
+可以添加更多安全选项：
+```
+PrivateDevices=yes
+ProtectKernelTunables=yes
+```
+
+3. **重新加载 systemd**
+   ```bash
+   sudo systemctl daemon-reload
+   ```
+
+4. **重启服务**
+   ```bash
+   sudo systemctl restart xxxigcc-proxy
+   ```
+
+## 安全建议
+
+- 最小权限原则
+- 谨慎修改默认配置
+- 定期审查服务权限
+- 测试每项更改的影响

llmdoc/guides/how-to-trigger-release.md

@@ -0,0 +1,56 @@
+# 如何触发 Release
+
+## 1. 发布前提条件
+- 代码已提交并合并到 `main` 分支
+- 确定新版本号（如 `3.4.8-xg1`）
+
+## 2. 发布方式
+
+### 方式一：创建 Git Tag（推荐）
+1. 本地创建 tag
+```bash
+git tag 3.4.8-xg1
+git push origin 3.4.8-xg1
+```
+
+### 方式二：Gitea Web 界面
+1. 在 Gitea 仓库页面
+2. 点击 "发布"
+3. 创建新 Tag
+
+## 3. 构建和发布流程
+
+### 自动触发条件
+- 推送到 `main`/`develop` 分支
+- 推送新的 Tag
+
+### 构建矩阵
+- 架构：amd64、arm64
+- 发行版：Ubuntu、Alpine
+
+## 4. 验证发布
+
+### 检查构建产物
+- Generic Package Registry
+- Debian Package Registry
+- GitHub/Gitea Release 页面
+
+### 下载和测试
+1. 直接从 Release 下载
+2. 通过 Debian 仓库安装
+```bash
+sudo apt-get update
+sudo apt-get install xxxigcc-proxy
+```
+
+## 5. 常见问题
+
+### 构建失败
+- 检查 CI 日志
+- 验证代码是否通过所有测试
+- 确认依赖项是否正确
+
+### 包上传失败
+- 检查 Build Token 权限
+- 验证网络连接
+- 确认包管理器配置

llmdoc/guides/troubleshooting-docker-builds.md

@@ -0,0 +1,60 @@
+# Docker 构建问题排查指南
+
+## 常见构建错误
+
+### 1. 依赖安装失败
+**症状**：软件包无法下载或安装
+
+**解决方案**：
+- 检查网络连接
+- 更新 `sources.list` 或 `repositories`
+- 手动安装缺失依赖
+- 检查架构兼容性
+
+### 2. 交叉编译问题
+**症状**：编译过程中出现架构不兼容错误
+
+**诊断步骤**：
+- 验证交叉编译工具链
+- 检查 `CMakeLists.txt` 配置
+- 降低并行编译作业数
+- 查看完整编译日志
+
+### 3. BuildX 配置问题
+**症状**：多架构构建失败
+
+**排查清单**：
+- 确认 BuildX 实例正常
+- 检查 `--platform` 参数
+- 验证 Docker 版本兼容性
+- 重置 BuildX 实例
+
+### 4. 镜像大小异常
+**症状**：构建镜像unexpectedly大
+
+**优化建议**：
+- 使用多阶段构建
+- 删除不必要的构建缓存
+- 精简基础镜像
+- 仅复制必要的二进制文件
+
+## 调试工具和命令
+
+### BuildX 诊断
+```bash
+docker buildx ls
+docker buildx inspect
+docker buildx debug
+```
+
+### 构建日志分析
+```bash
+docker buildx build --progress=plain
+```
+
+## 最佳实践
+
+- 始终使用 `--no-cache` 进行初始调试
+- 保持 Dockerfile 简洁
+- 定期更新基础镜像和依赖
+- 遵循最小权限原则