From 9afe4a864954cd145745d5fc68c7e85dfeafc71a Mon Sep 17 00:00:00 2001 From: Wang Defa Date: Thu, 25 Dec 2025 10:18:07 +0800 Subject: [PATCH] =?UTF-8?q?=E7=AE=80=E5=8C=96=20Debian=20=E5=8F=91?= =?UTF-8?q?=E5=B8=83=E6=B5=81=E7=A8=8B=E5=B9=B6=E6=B7=BB=E5=8A=A0=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E7=B3=BB=E7=BB=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将 Debian 包仓库从 bookworm/trixie 双发行版改为通用 stable 仓库 - 新增完整的 llmdoc 文档系统，包含架构、指南和参考文档 - 更新 README.md 和部署指南以反映新的仓库配置 - 添加 .gitignore 文件 --- .gitea/workflows/ci.yaml | 24 ++--- .gitignore | 2 + README.md | 20 ++-- debian/build-deb.sh | 2 +- llmdoc/architecture/cicd-pipeline.md | 59 ++++++++++++ llmdoc/architecture/debian-packaging.md | 35 +++++++ .../architecture/deployment-architecture.md | 30 ++++++ llmdoc/architecture/docker-build-system.md | 45 +++++++++ llmdoc/architecture/multi-arch-strategy.md | 48 ++++++++++ llmdoc/architecture/release-process.md | 66 ++++++++++++++ .../architecture/source-code-modification.md | 77 ++++++++++++++++ llmdoc/architecture/systemd-service.md | 49 ++++++++++ llmdoc/guides/how-to-build-debian-package.md | 42 +++++++++ llmdoc/guides/how-to-build-docker-images.md | 55 +++++++++++ llmdoc/guides/how-to-configure.md | 57 ++++++++++++ llmdoc/guides/how-to-deploy.md | 59 ++++++++++++ llmdoc/guides/how-to-modify-cicd-workflow.md | 73 +++++++++++++++ llmdoc/guides/how-to-modify-source-code.md | 91 +++++++++++++++++++ .../guides/how-to-modify-systemd-service.md | 51 +++++++++++ llmdoc/guides/how-to-trigger-release.md | 56 ++++++++++++ .../guides/troubleshooting-docker-builds.md | 60 ++++++++++++ llmdoc/index.md | 68 ++++++++++++++ llmdoc/overview/project-overview.md | 29 ++++++ llmdoc/reference/coding-conventions.md | 62 +++++++++++++ llmdoc/reference/configuration-options.md | 39 ++++++++ llmdoc/reference/debian-package-structure.md | 49 ++++++++++ llmdoc/reference/git-conventions.md | 43 +++++++++ llmdoc/reference/modification-checklist.md | 37 ++++++++ 28 files changed, 1297 insertions(+), 31 deletions(-) create mode 100644 .gitignore create mode 100644 llmdoc/architecture/cicd-pipeline.md create mode 100644 llmdoc/architecture/debian-packaging.md create mode 100644 llmdoc/architecture/deployment-architecture.md create mode 100644 llmdoc/architecture/docker-build-system.md create mode 100644 llmdoc/architecture/multi-arch-strategy.md create mode 100644 llmdoc/architecture/release-process.md create mode 100644 llmdoc/architecture/source-code-modification.md create mode 100644 llmdoc/architecture/systemd-service.md create mode 100644 llmdoc/guides/how-to-build-debian-package.md create mode 100644 llmdoc/guides/how-to-build-docker-images.md create mode 100644 llmdoc/guides/how-to-configure.md create mode 100644 llmdoc/guides/how-to-deploy.md create mode 100644 llmdoc/guides/how-to-modify-cicd-workflow.md create mode 100644 llmdoc/guides/how-to-modify-source-code.md create mode 100644 llmdoc/guides/how-to-modify-systemd-service.md create mode 100644 llmdoc/guides/how-to-trigger-release.md create mode 100644 llmdoc/guides/troubleshooting-docker-builds.md create mode 100644 llmdoc/index.md create mode 100644 llmdoc/overview/project-overview.md create mode 100644 llmdoc/reference/coding-conventions.md create mode 100644 llmdoc/reference/configuration-options.md create mode 100644 llmdoc/reference/debian-package-structure.md create mode 100644 llmdoc/reference/git-conventions.md create mode 100644 llmdoc/reference/modification-checklist.md diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 635f08b..a1b605e 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -9,7 +9,7 @@ on: env: DOCKER_BUILDKIT: "1" PRODUCT_NAME: "xxxigcc-proxy" - PACKAGE_VERSION: "3.4.6-xg2" + PACKAGE_VERSION: "3.4.8-xg1" BUILDX_NO_DEFAULT_ATTESTATIONS: "1" jobs: @@ -134,29 +134,19 @@ jobs: } done - # 上传 Debian 包到 Debian Package Registry (支持多个发行版) + # 上传 Debian 包到 Debian Package Registry (通用稳定版) echo "" echo "📦 上传 Debian 包到 Debian Package Registry..." for file in *.deb; do [ ! -f "$file" ] && continue - # 上传到 bookworm (Debian 12) - echo " ⬆️ $file → bookworm" + # 上传到 stable (通用稳定版) + echo " ⬆️ $file → stable" curl -fsSL -X PUT \ -H "Authorization: token ${TOKEN}" \ --upload-file "$file" \ - "https://${REGISTRY}/api/packages/${OWNER}/debian/pool/bookworm/main/upload" || { - echo "❌ Debian 包上传失败: $file (bookworm)" - exit 1 - } - - # 上传到 trixie (Debian 13) - echo " ⬆️ $file → trixie" - curl -fsSL -X PUT \ - -H "Authorization: token ${TOKEN}" \ - --upload-file "$file" \ - "https://${REGISTRY}/api/packages/${OWNER}/debian/pool/trixie/main/upload" || { - echo "❌ Debian 包上传失败: $file (trixie)" + "https://${REGISTRY}/api/packages/${OWNER}/debian/pool/stable/main/upload" || { + echo "❌ Debian 包上传失败: $file (stable)" exit 1 } done @@ -166,7 +156,7 @@ jobs: echo "📝 生成 Release..." export REGISTRY OWNER TAG - RELEASE_DATA=$(python3 -c 'import json,glob,os;r=os.environ["REGISTRY"];o=os.environ["OWNER"];p=os.environ["PRODUCT_NAME"];t=os.environ["TAG"];b=["## Release "+t,"","### 📥 下载方式","","#### 方式 1: 直接下载（推荐）","","点击下面 **Assets** 部分的文件名直接下载。","","#### 方式 2: Generic Package Registry",""]+[f"- [`{f}`](https://{r}/api/packages/{o}/generic/{p}/{t}/{f})" for f in sorted(glob.glob("*.tar.gz"))]+["","#### 方式 3: Debian Repository","","**Debian 12 (bookworm):**","","```bash","# Download GPG key",f"sudo curl https://{r}/api/packages/{o}/debian/repository.key -o /etc/apt/keyrings/gitea-{o}.asc","","# Add repository",f"echo \"deb [signed-by=/etc/apt/keyrings/gitea-{o}.asc] https://{r}/api/packages/{o}/debian bookworm main\" | sudo tee -a /etc/apt/sources.list.d/{o}.list","","# Update and install","sudo apt-get update","sudo apt-get install xxxigcc-proxy","```","","**Debian 13 (trixie):**","","```bash","# Download GPG key",f"sudo curl https://{r}/api/packages/{o}/debian/repository.key -o /etc/apt/keyrings/gitea-{o}.asc","","# Add repository",f"echo \"deb [signed-by=/etc/apt/keyrings/gitea-{o}.asc] https://{r}/api/packages/{o}/debian trixie main\" | sudo tee -a /etc/apt/sources.list.d/{o}.list","","# Update and install","sudo apt-get update","sudo apt-get install xxxigcc-proxy","```"];print(json.dumps({"tag_name":t,"name":f"Release {t}","body":"\n".join(b),"draft":False,"prerelease":False}))') + RELEASE_DATA=$(python3 -c 'import json,glob,os;r=os.environ["REGISTRY"];o=os.environ["OWNER"];p=os.environ["PRODUCT_NAME"];t=os.environ["TAG"];b=["## Release "+t,"","### 📥 下载方式","","#### 方式 1: 直接下载（推荐）","","点击下面 **Assets** 部分的文件名直接下载。","","#### 方式 2: Generic Package Registry",""]+[f"- [`{f}`](https://{r}/api/packages/{o}/generic/{p}/{t}/{f})" for f in sorted(glob.glob("*.tar.gz"))]+["","#### 方式 3: Debian Repository","","```bash","# Download GPG key",f"sudo curl https://{r}/api/packages/{o}/debian/repository.key -o /etc/apt/keyrings/gitea-{o}.asc","","# Add repository",f"echo \"deb [signed-by=/etc/apt/keyrings/gitea-{o}.asc] https://{r}/api/packages/{o}/debian stable main\" | sudo tee -a /etc/apt/sources.list.d/{o}.list","","# Update and install","sudo apt-get update","sudo apt-get install xxxigcc-proxy","```"];print(json.dumps({"tag_name":t,"name":f"Release {t}","body":"\n".join(b),"draft":False,"prerelease":False}))') # 创建 Release echo "" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c863b59 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.idea/ +.claude/ \ No newline at end of file diff --git a/README.md b/README.md index 9b64a1d..0a81f43 100644 --- a/README.md +++ b/README.md @@ -11,26 +11,20 @@ - 🏗️ **多架构**：原生支持 AMD64 和 ARM64 架构 - 📦 **多种格式**：提供二进制包 (.tar.gz) 和 Debian 软件包 (.deb) - 🐧 **多发行版**：支持 Ubuntu 和 Alpine Linux -- 🔄 **自动更新**：可通过 Debian 仓库安装 (bookworm/trixie) +- 🔄 **自动更新**：可通过 Debian 仓库安装（通用稳定版） ## 🚀 快速开始 ### Debian/Ubuntu（推荐） -**Debian 12 (bookworm):** - ```bash +# 下载 GPG 密钥 sudo curl https://gitea.bcde.io/api/packages/wangdefa/debian/repository.key -o /etc/apt/keyrings/gitea-wangdefa.asc -echo "deb [signed-by=/etc/apt/keyrings/gitea-wangdefa.asc] https://gitea.bcde.io/api/packages/wangdefa/debian bookworm main" | sudo tee -a /etc/apt/sources.list.d/wangdefa.list -sudo apt-get update -sudo apt-get install xxxigcc-proxy -``` -**Debian 13 (trixie):** +# 添加仓库 +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 -```bash -sudo curl https://gitea.bcde.io/api/packages/wangdefa/debian/repository.key -o /etc/apt/keyrings/gitea-wangdefa.asc -echo "deb [signed-by=/etc/apt/keyrings/gitea-wangdefa.asc] https://gitea.bcde.io/api/packages/wangdefa/debian trixie main" | sudo tee -a /etc/apt/sources.list.d/wangdefa.list +# 更新并安装 sudo apt-get update sudo apt-get install xxxigcc-proxy ``` @@ -41,8 +35,8 @@ sudo apt-get install xxxigcc-proxy ```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 +wget https://gitea.bcde.io/api/packages/wangdefa/generic/xxxigcc-proxy/3.4.8-xg1/xxxigcc-proxy-amd64-ubuntu-3.4.8-xg1.tar.gz +tar -xzf xxxigcc-proxy-amd64-ubuntu-3.4.8-xg1.tar.gz # 运行 ./xxxigcc-proxy --config=config.json diff --git a/debian/build-deb.sh b/debian/build-deb.sh index e67679f..ea7c553 100755 --- a/debian/build-deb.sh +++ b/debian/build-deb.sh @@ -4,7 +4,7 @@ set -e # 参数检查 if [ $# -ne 3 ]; then echo "Usage: $0 " - echo "Example: $0 amd64 3.4.6-xg2 xxxigcc-proxy-amd64-ubuntu-3.4.6-xg2.tar.gz" + echo "Example: $0 amd64 3.4.8-xg1 xxxigcc-proxy-amd64-ubuntu-3.4.8-xg1.tar.gz" exit 1 fi diff --git a/llmdoc/architecture/cicd-pipeline.md b/llmdoc/architecture/cicd-pipeline.md new file mode 100644 index 0000000..6cf4f78 --- /dev/null +++ b/llmdoc/architecture/cicd-pipeline.md @@ -0,0 +1,59 @@ +# CI/CD 流水线架构 + +## 1. 身份与目的 +- **名称：** xxxigcc-proxy 自动化构建和发布流水线 +- **目的：** 自动化构建、测试和发布跨平台二进制包和 Debian 安装包 + +## 2. 核心组件 + +### 2.1 构建作业 (build-and-test) +`架构路径：.gitea/workflows/ci.yaml:15-93` + +#### 主要职责 +- 多架构（amd64、arm64）构建 +- 多发行版（Ubuntu、Alpine）构建 +- 构建二进制文件 +- 打包 tar.gz 文件 +- 构建 Debian 安装包 +- 上传构建产物 + +#### 关键步骤 +1. 代码检出 +2. 设置 Docker Buildx +3. 构建二进制文件（`docker buildx build`） +4. 打包和测试（创建 tar.gz） +5. 构建 Debian 包（仅 Ubuntu） +6. 上传构建产物 + +### 2.2 发布作业 (release) +`架构路径：.gitea/workflows/ci.yaml:95-212` + +#### 主要职责 +- 下载构建产物 +- 上传包到包管理器 +- 创建 GitHub/Gitea Release +- 生成发布说明 +- 上传发布附件 + +#### 关键步骤 +1. 下载构建产物 +2. 上传到 Generic Package Registry +3. 上传到 Debian Package Registry +4. 创建 Release +5. 上传 Release 附件 + +## 3. 设计原理 + +### 多架构构建 +- 使用 Docker Buildx 实现跨平台构建 +- 支持 AMD64 和 ARM64 架构 +- 针对不同架构和发行版生成独立构建 + +### 包管理策略 +- Generic Package Registry：存储 tar.gz 包 +- Debian Package Registry：使用通用 `stable` 发行版，支持所有 Debian/Ubuntu 发行版 +- 自动生成安装和下载说明 + +## 4. 触发机制 +- 代码推送到 main/develop 分支 +- 标签（Tag）推送时触发发布流程 \ No newline at end of file diff --git a/llmdoc/architecture/debian-packaging.md b/llmdoc/architecture/debian-packaging.md new file mode 100644 index 0000000..8c72180 --- /dev/null +++ b/llmdoc/architecture/debian-packaging.md @@ -0,0 +1,35 @@ +# Debian 包构建架构 + +## 1. 身份 + +- **定义：** Debian 打包系统，用于将 xxxigcc-proxy 软件打包为可安装的 Debian 软件包。 +- **目的：** 提供一个标准化的软件分发和安装机制。 + +## 2. 核心组件 + +- `debian/build-deb.sh`: 主要构建脚本，负责整个 Debian 包的构建过程 + - 架构转换 + - 目录结构创建 + - 文件复制与权限设置 + - 包构建 + +- `debian/control.template`: 定义包的元数据 + - 包名、版本、依赖关系 + - 描述和维护者信息 + +## 3. 执行流程 + +1. **初始化**：接收架构、版本和源文件作为输入 +2. **目录准备**：创建临时构建目录 +3. **二进制文件解压**：将源 tar.gz 文件解压到 `/opt/xxxigcc-proxy` +4. **控制文件生成**：使用 `sed` 替换模板变量 +5. **维护脚本复制**：复制 postinst, prerm, postrm 脚本 +6. **服务文件安装**：复制 systemd 服务配置文件 +7. **权限设置**：调整关键文件和目录权限 +8. **包构建**：使用 `dpkg-deb` 构建最终的 .deb 包 + +## 4. 设计原理 + +- 使用模板和脚本实现灵活的构建过程 +- 遵循 Debian 打包规范 +- 确保软件及其依赖能在目标系统正确安装和运行 \ No newline at end of file diff --git a/llmdoc/architecture/deployment-architecture.md b/llmdoc/architecture/deployment-architecture.md new file mode 100644 index 0000000..6b6c9c6 --- /dev/null +++ b/llmdoc/architecture/deployment-architecture.md @@ -0,0 +1,30 @@ +# XXXigCC Proxy 部署架构 + +## 1. 身份与目的 + +- **定义**：一个专注于零捐赠的 XMRigCC 代理服务 +- **主要目的**：提供可靠、安全的加密货币挖矿代理服务 + +## 2. 核心组件 + +`debian/xxxigcc-proxy.service` (SystemdServiceDefinition): 定义了服务的运行时行为和安全配置。 + +- **关键职责**： + 1. 定义服务启动方式 + 2. 配置系统资源限制 + 3. 设置安全运行参数 + +## 3. 执行流程（LLM 检索路径） + +- **1. 服务初始化**：SystemD 通过 `xxxigcc-proxy.service` 启动服务 +- **2. 配置加载**：读取 `/etc/xxxigcc-proxy/config.json` +- **3. 日志系统**： + - 常规日志：`/var/log/xxxigcc-proxy/proxy.log` + - 访问日志：`/var/log/xxxigcc-proxy/access.log` + +## 4. 设计原则 + +- 最小权限原则 +- 资源受限运行 +- 详细日志记录 +- 自动重启机制 \ No newline at end of file diff --git a/llmdoc/architecture/docker-build-system.md b/llmdoc/architecture/docker-build-system.md new file mode 100644 index 0000000..cf86d4a --- /dev/null +++ b/llmdoc/architecture/docker-build-system.md @@ -0,0 +1,45 @@ +# Docker 构建系统架构 + +## 1. 系统身份 + +- **定义**：高度自动化且灵活的多架构 Docker 构建系统 +- **目的**：支持跨平台（`amd64`、`arm64`）和多发行版（Ubuntu、Alpine）的容器化构建 + +## 2. 核心组件 + +`- docker/Dockerfile.ubuntu` (`base`, `build`): Ubuntu 22.04 多阶段构建镜像 +`- docker/Dockerfile.alpine` (`base`, `build`): Alpine Linux 多阶段构建镜像 +`- .gitea/workflows/ci.yaml` (`BuildX`, `matrix`): Docker 多架构构建工作流 + +## 3. 执行流程（LLM 检索映射） + +### 多阶段构建流程 +1. **基础阶段（`base`）**： + - 安装基础编译依赖 + - 准备编译环境 + +2. **构建阶段（`build`）**： + - 克隆源代码 + - 执行 `init.sh` 进行项目初始化 + - 使用 CMake 编译项目 + +3. **最终镜像阶段**： + - 仅保留编译产物 + - 创建最小化镜像 + +### 多架构支持关键机制 +- 使用 `TARGETARCH`、`BUILDPLATFORM` 动态调整构建 +- 交叉编译时降低并行度（`-j2`） +- 本地编译使用全部 CPU 核心（`-j$(nproc)`） + +## 4. 设计原理 + +### 构建优化策略 +- 使用 Docker BuildKit 加速构建 +- 禁用不必要的构建证明 +- 动态调整构建作业并行度 + +### 跨平台兼容性 +- 通过 `init.sh` 实现统一的项目初始化 +- 支持 `amd64`、`arm64` 架构 +- 兼容 Ubuntu 和 Alpine 发行版 \ No newline at end of file diff --git a/llmdoc/architecture/multi-arch-strategy.md b/llmdoc/architecture/multi-arch-strategy.md new file mode 100644 index 0000000..c84a656 --- /dev/null +++ b/llmdoc/architecture/multi-arch-strategy.md @@ -0,0 +1,48 @@ +# 多架构构建策略详解 + +## 1. 架构支持 + +### 目标架构 +- `amd64`（x86_64） +- `arm64`（ARM 64位） + +## 2. 交叉编译优化 + +### 编译参数调整 +- 跨平台编译时：`MAKE_JOBS=-j2` +- 本地平台编译：`MAKE_JOBS=-j$(nproc)` + +### 关键构建参数 +- `TARGETARCH`：目标架构 +- `BUILDPLATFORM`：构建主机架构 +- `TARGETPLATFORM`：完整目标平台信息 + +## 3. 依赖管理 + +### 架构相关依赖处理 +- Ubuntu：通过 `apt-get` 安装依赖 +- Alpine：使用 `apk add` 安装跨平台工具链 + +### 关键依赖工具 +- `gcc`/`g++`：编译器 +- `cmake`：跨平台构建系统 +- `libuv-dev`：异步 I/O 库 +- `libssl-dev`：SSL/TLS 库 +- `hwloc-dev`：硬件定位库 + +## 4. 构建流程优化 + +### BuildKit 配置 +- 启用 `DOCKER_BUILDKIT=1` +- 禁用默认构建证明 `BUILDX_NO_DEFAULT_ATTESTATIONS=1` + +### 构建缓存策略 +- 多阶段构建减少最终镜像大小 +- 分层缓存提高重复构建效率 + +## 5. 最佳实践 + +### 跨平台兼容性 +- 使用 `init.sh` 统一项目配置 +- 确保代码和构建脚本平台无关 +- 避免硬编码平台相关的路径或命令 \ No newline at end of file diff --git a/llmdoc/architecture/release-process.md b/llmdoc/architecture/release-process.md new file mode 100644 index 0000000..f5591e7 --- /dev/null +++ b/llmdoc/architecture/release-process.md @@ -0,0 +1,66 @@ +# 发布流程架构 + +## 1. 身份与目的 +- **名称：** xxxigcc-proxy 发布流程 +- **目的：** 定义软件包分发和版本管理的标准流程 + +## 2. 包管理注册表 + +### 2.1 Generic Package Registry +`架构路径：.gitea/workflows/ci.yaml:125-135` + +#### 特点 +- 存储 tar.gz 二进制包 +- 直接可下载链接 +- 版本化管理 + +#### 上传逻辑 +- 基于 curl 的 PUT 请求 +- 使用 Build Token 认证 +- 上传路径：`/api/packages/{owner}/generic/{product_name}/{version}/{filename}` + +### 2.2 Debian Package Registry +`架构路径：.gitea/workflows/ci.yaml:137-152` + +#### 特点 +- 通用稳定版仓库 +- 支持所有 Debian/Ubuntu 发行版 +- 单一 `stable` 发行版代号 + +#### 上传逻辑 +- 使用 curl 的 PUT 请求 +- 上传到通用稳定版仓库 +- 上传路径：`/api/packages/{owner}/debian/pool/stable/main/upload` + +## 3. Release 生成策略 + +### 3.1 Release 内容 +`架构路径：.gitea/workflows/ci.yaml:154-159` + +#### 发布说明生成 +- 使用 Python 动态生成 Markdown 格式 +- 包含多种下载方式说明 +- 提供仓库和直接下载链接 + +### 3.2 Release 创建 +`架构路径：.gitea/workflows/ci.yaml:161-188` + +#### 创建流程 +- 使用 Gitea API 创建 Release +- 处理重复 Release 的情况 +- 生成 Release JSON payload + +### 3.3 附件上传 +`架构路径：.gitea/workflows/ci.yaml:190-204` + +#### 上传策略 +- 上传 tar.gz 和 .deb 文件 +- 作为 Release 附件 +- 使用 multipart/form-data + +## 4. 安装指南生成 +生成通用 Debian 仓库的安装说明，包括： +- GPG 密钥下载 +- 仓库添加（使用 `stable` 发行版代号） +- 包安装命令 +- 支持所有 Debian/Ubuntu 发行版 \ No newline at end of file diff --git a/llmdoc/architecture/source-code-modification.md b/llmdoc/architecture/source-code-modification.md new file mode 100644 index 0000000..69a9624 --- /dev/null +++ b/llmdoc/architecture/source-code-modification.md @@ -0,0 +1,77 @@ +# 源代码修改架构 + +## 1. 修改策略概述 + +本文档详细阐述了 XXXigCC Proxy 项目的源代码修改架构，重点介绍 `init.sh` 脚本的工作原理和修改策略。 + +## 2. 修改类型和范围 + +### 2.1 项目重命名 +- **文件：** `CMakeLists.txt` +- **修改方式：** 使用 `sed` 替换 `project(xmrigcc-proxy)` 为 `project(xxxigcc-proxy)` +- **影响：** 更改项目构建时的名称标识 + +### 2.2 捐赠功能修改 +- **目标：** 完全禁用捐赠机制 +- **修改文件：** + * `src/donate.h` + * `src/net/strategies/DonateStrategy.cpp` + * `src/core/config/Config_platform.h` + * `src/config.json` +- **具体修改：** + - 将捐赠级别从 2 降至 0 + - 将捐赠服务器地址重定向到 `127.0.0.1` + +### 2.3 版本信息定制 +- **文件：** `src/version.h` +- **修改：** + - 将 "xmrigcc" 替换为 "xxxigcc" + - 将 "XMRigCC" 替换为 "XXXigCC" + +### 2.4 调试配置 +- **文件：** `src/config.json` +- **修改：** 将 `"verbose"` 设置为 `true`，启用详细日志输出 + +## 3. 修改实现技术 + +### 3.1 sed 命令策略 +- 使用 `-i` 参数直接原地修改文件 +- 采用精确的字符串替换 +- 覆盖多个源代码和配置文件 + +### 3.2 关键修改命令示例 + +```bash +# 项目重命名 +sed -i 's/project(xmrigcc-proxy)/project(xxxigcc-proxy)/' CMakeLists.txt + +# 捐赠级别修改 +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 + +# 捐赠服务器地址修改 +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 + +# 版本字符串修改 +sed -i 's/xmrigcc/xxxigcc/' src/version.h +sed -i 's/XMRigCC/XXXigCC/' src/version.h +``` + +## 4. 架构设计原则 + +- 保留原项目基本结构 +- 通过前缀变更（xmr → xxx）实现项目个性化 +- 维持原代码仓库的基本架构和功能 + +## 5. 修改意图 + +- 个性化原始项目 +- 完全移除捐赠功能 +- 提供更详细的调试信息 + +## 6. 关键关联文件 + +- `init.sh`：负责初始化和定制项目 +- 修改涉及多个源代码和配置文件 +- 修改范围覆盖编译配置、运行时配置和版本信息 \ No newline at end of file diff --git a/llmdoc/architecture/systemd-service.md b/llmdoc/architecture/systemd-service.md new file mode 100644 index 0000000..2afb866 --- /dev/null +++ b/llmdoc/architecture/systemd-service.md @@ -0,0 +1,49 @@ +# Systemd 服务配置架构 + +## 1. 身份 + +- **定义：** xxxigcc-proxy 的 systemd 服务配置 +- **目的：** 提供一个安全、可靠的服务管理机制 + +## 2. 核心配置 + +`debian/xxxigcc-proxy.service` 文件定义了服务的关键特性： + +### 启动控制 +- `Type=simple`：直接启动进程 +- `After=network.target`：确保网络就绪后启动 +- `Restart=always`：服务意外停止时自动重启 +- `RestartSec=10`：重启间隔 10 秒 + +### 安全设置 +- `NoNewPrivileges=true`：禁止进程获取新权限 +- `PrivateTmp=true`：隔离临时文件目录 +- `ProtectSystem=strict`：限制对系统目录的修改 +- `ProtectHome=true`：保护用户主目录 + +### 资源限制 +- `LimitNOFILE=65535`：最大文件描述符数 +- `LimitNPROC=4096`：最大进程数 + +### 用户和组 +- 以 `xxxigcc-proxy` 专用用户运行 +- 降低潜在安全风险 + +### 日志管理 +- 使用 systemd journal 记录日志 +- 标准输出和错误重定向到日志系统 + +## 3. 执行流程 + +1. systemd 检查网络就绪 +2. 以 `xxxigcc-proxy` 用户启动进程 +3. 使用指定配置文件和日志路径启动 +4. 持续监控服务状态 +5. 必要时自动重启服务 + +## 4. 设计原则 + +- 最小权限原则 +- 服务可靠性 +- 安全隔离 +- 日志完整性 \ No newline at end of file diff --git a/llmdoc/guides/how-to-build-debian-package.md b/llmdoc/guides/how-to-build-debian-package.md new file mode 100644 index 0000000..faff9fe --- /dev/null +++ b/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） +- 验证源代码完整性 \ No newline at end of file diff --git a/llmdoc/guides/how-to-build-docker-images.md b/llmdoc/guides/how-to-build-docker-images.md new file mode 100644 index 0000000..06c8153 --- /dev/null +++ b/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 实例状态 +- 验证依赖工具链 +- 查看详细构建日志 \ No newline at end of file diff --git a/llmdoc/guides/how-to-configure.md b/llmdoc/guides/how-to-configure.md new file mode 100644 index 0000000..7cac92b --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/llmdoc/guides/how-to-deploy.md b/llmdoc/guides/how-to-deploy.md new file mode 100644 index 0000000..c78f56b --- /dev/null +++ b/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` \ No newline at end of file diff --git a/llmdoc/guides/how-to-modify-cicd-workflow.md b/llmdoc/guides/how-to-modify-cicd-workflow.md new file mode 100644 index 0000000..63b618b --- /dev/null +++ b/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. 最佳实践 + +- 保持向后兼容性 +- 详细记录工作流变更 +- 增量测试新功能 +- 遵循现有的构建和打包模式 \ No newline at end of file diff --git a/llmdoc/guides/how-to-modify-source-code.md b/llmdoc/guides/how-to-modify-source-code.md new file mode 100644 index 0000000..653647f --- /dev/null +++ b/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. 最佳实践 + +- 始终在版本控制系统中工作 +- 为每次重大修改创建单独的分支 +- 保留原始项目的基本架构和功能 +- 充分测试每一个修改 \ No newline at end of file diff --git a/llmdoc/guides/how-to-modify-systemd-service.md b/llmdoc/guides/how-to-modify-systemd-service.md new file mode 100644 index 0000000..0695f73 --- /dev/null +++ b/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 + ``` + +## 安全建议 + +- 最小权限原则 +- 谨慎修改默认配置 +- 定期审查服务权限 +- 测试每项更改的影响 \ No newline at end of file diff --git a/llmdoc/guides/how-to-trigger-release.md b/llmdoc/guides/how-to-trigger-release.md new file mode 100644 index 0000000..45323be --- /dev/null +++ b/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 权限 +- 验证网络连接 +- 确认包管理器配置 \ No newline at end of file diff --git a/llmdoc/guides/troubleshooting-docker-builds.md b/llmdoc/guides/troubleshooting-docker-builds.md new file mode 100644 index 0000000..93fac8e --- /dev/null +++ b/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 简洁 +- 定期更新基础镜像和依赖 +- 遵循最小权限原则 \ No newline at end of file diff --git a/llmdoc/index.md b/llmdoc/index.md new file mode 100644 index 0000000..cea36b9 --- /dev/null +++ b/llmdoc/index.md @@ -0,0 +1,68 @@ +# XXXigCC Proxy 项目文档 + +> XXXigCC Proxy 是一个基于 XMRigCC Proxy 的修改版本，专注于禁用捐赠功能，提供多架构、多发行版支持的挖矿代理服务。 + +## 📖 项目概览 + +- [项目概述](overview/project-overview.md) - 项目简介、核心特性和背景 + +## 🏗️ 架构文档 + +### 源代码修改 +- [源代码修改架构](architecture/source-code-modification.md) - init.sh 脚本的工作原理和修改策略 + +### 构建系统 +- [Docker 构建系统](architecture/docker-build-system.md) - Docker BuildX 多架构构建系统 +- [多架构构建策略](architecture/multi-arch-strategy.md) - amd64/arm64 架构支持的实现细节 + +### CI/CD 发布 +- [CI/CD 流水线架构](architecture/cicd-pipeline.md) - Gitea Actions 自动化构建和发布流程 +- [发布流程架构](architecture/release-process.md) - Generic 和 Debian Package Registry 的使用 + +### Debian 打包 +- [Debian 包构建架构](architecture/debian-packaging.md) - Debian 包的构建流程和结构 +- [Systemd 服务配置架构](architecture/systemd-service.md) - 服务配置、安全设置和资源限制 + +### 部署 +- [部署架构](architecture/deployment-architecture.md) - 系统部署架构和配置管理 + +## 📚 操作指南 + +### 源代码修改 +- [如何修改源代码](guides/how-to-modify-source-code.md) - 修改 XMRigCC 源代码的详细步骤 + +### Docker 构建 +- [如何构建 Docker 镜像](guides/how-to-build-docker-images.md) - 本地构建多架构 Docker 镜像 +- [Docker 构建问题排查](guides/troubleshooting-docker-builds.md) - 常见构建错误和解决方案 + +### CI/CD 管理 +- [如何触发 Release](guides/how-to-trigger-release.md) - 创建新版本和发布的步骤 +- [如何修改 CI/CD 工作流](guides/how-to-modify-cicd-workflow.md) - 修改 Gitea Actions 工作流 + +### Debian 打包 +- [如何构建 Debian 包](guides/how-to-build-debian-package.md) - 本地构建 Debian 软件包 +- [如何修改 Systemd 服务](guides/how-to-modify-systemd-service.md) - 调整服务配置和安全设置 + +### 部署和配置 +- [部署指南](guides/how-to-deploy.md) - Debian 仓库、二进制包和 Docker 部署方式 +- [配置指南](guides/how-to-configure.md) - 配置文件说明和最佳实践 + +## 📋 参考文档 + +### 开发规范 +- [Shell 脚本编码规范](reference/coding-conventions.md) - Shell 脚本的编码标准和最佳实践 +- [Git 规范指南](reference/git-conventions.md) - 提交信息、分支管理和标签规范 + +### 技术参考 +- [源代码修改清单](reference/modification-checklist.md) - 所有修改点的清单和验证步骤 +- [Debian 包结构详解](reference/debian-package-structure.md) - Debian 包的目录结构和文件说明 +- [配置选项参考](reference/configuration-options.md) - 所有配置选项的详细说明 + +## 🔗 其他资源 + +- [许可证](../LICENSE) - GPL-3.0 开源许可证 +- [原始项目](https://github.com/Bendr0id/XMRigcc-Proxy) - XMRigCC Proxy 源项目 + +## ⚠️ 免责声明 + +本项目**仅供学习和研究使用**。用户需严格遵守当地法律法规，任何非法使用均与项目作者无关。 diff --git a/llmdoc/overview/project-overview.md b/llmdoc/overview/project-overview.md new file mode 100644 index 0000000..7408b00 --- /dev/null +++ b/llmdoc/overview/project-overview.md @@ -0,0 +1,29 @@ +# XXXigCC Proxy 项目概述 + +## 1. 身份定义 + +**XXXigCC Proxy** 是一个专注于零捐赠的 XMRigCC 代理服务，基于原始 XMRigCC Proxy 项目进行了定制修改。 + +## 2. 主要特性 + +- 零捐赠：捐赠级别设为 0 +- 多架构支持：原生支持 AMD64 和 ARM64 +- 多格式发行：提供二进制包和 Debian 软件包 +- 跨发行版兼容：支持 Ubuntu 和 Alpine Linux +- 自动更新：可通过 Debian 仓库安装 + +## 3. 项目背景 + +本项目基于 [Bendr0id/XMRigCC Proxy](https://github.com/Bendr0id/XMRigcc-Proxy)，主要进行了以下改进： + +1. 完全禁用捐赠功能 +2. 捐赠端点重定向到本地 +3. 默认启用详细日志 +4. 项目名称调整为 "xxxigcc" + +## 4. 使用场景 + +适合需要： +- 精确控制代理服务 +- 最小化额外开销 +- 灵活部署的加密货币挖矿环境 \ No newline at end of file diff --git a/llmdoc/reference/coding-conventions.md b/llmdoc/reference/coding-conventions.md new file mode 100644 index 0000000..f8187db --- /dev/null +++ b/llmdoc/reference/coding-conventions.md @@ -0,0 +1,62 @@ +# Shell 脚本编码规范 + +## 1. 基本原则 + +### 1.1 Shell 类型 +- 优先使用 `#!/bin/sh`（POSIX shell） +- 复杂脚本可使用 `#!/bin/bash` + +### 1.2 安全性与健壮性 +- 始终使用 `set -e` 在任何错误发生时立即退出脚本 +- 对关键步骤进行错误检查和参数验证 + +## 2. 脚本结构 + +### 2.1 参数检查 +- 在脚本开始阶段进行参数数量和类型验证 +- 提供清晰的使用说明和示例 +- 对不合法输入给出明确的错误消息并退出 + +### 2.2 变量命名 +- 使用全大写字母表示常量和环境变量（如 `PRODUCT_NAME`） +- 使用小写字母并用下划线分隔表示局部变量（如 `build_dir`） +- 避免使用单字母变量名 + +## 3. 错误处理 + +### 3.1 临时文件管理 +- 使用 `mktemp` 创建安全的临时目录 +- 使用 `trap` 确保临时文件/目录在脚本结束时被清理 + +### 3.2 错误输出 +- 使用 `>&2` 将错误信息输出到标准错误流 +- 对于错误情况，使用非零退出码 + +## 4. 控制流 + +### 4.1 条件语句 +- 使用 `[ ]` 进行条件测试（兼容性更好） +- 避免复杂的嵌套条件语句，保持代码清晰 + +### 4.2 循环和分支 +- 在 `case` 语句中总是包含 `*)` 通配分支 +- 对于复杂的条件选择，使用 `case` 而非过长的 `if-elif` 链 + +## 5. 注释与文档 + +### 5.1 注释风格 +- 使用 `#` 进行单行注释 +- 为复杂的命令或逻辑块添加简洁的注释说明 +- 在脚本顶部添加简要的脚本用途说明 + +## 6. 执行与权限 + +### 6.1 文件权限 +- 明确设置脚本和生成文件的执行权限 +- 对于系统服务文件，使用标准权限模式（如 `755`、`644`） + +## 7. 实践建议 + +- 保持脚本简洁，单一职责 +- 避免使用晦涩的命令和技巧 +- 优先考虑可读性和可维护性 \ No newline at end of file diff --git a/llmdoc/reference/configuration-options.md b/llmdoc/reference/configuration-options.md new file mode 100644 index 0000000..e5c2297 --- /dev/null +++ b/llmdoc/reference/configuration-options.md @@ -0,0 +1,39 @@ +# XXXigCC Proxy 配置选项参考 + +## 配置文件位置 +- Debian 包：`/etc/xxxigcc-proxy/config.json` +- 二进制版本：`./config.json` + +## 核心配置选项 + +### 网络配置 +- `bind`: 监听地址和端口 + - 类型：字符串 + - 默认值：`"0.0.0.0:3333"` + - 示例：`"127.0.0.1:8080"` + +### 矿池配置 +- `pools`: 上游矿池列表 + - 类型：数组 + - 每个矿池包含： + - `url`: 矿池地址和端口 + - `user`: 钱包地址 + - `pass`: 矿池认证密码 + +### 日志配置 +- `log-file`: 常规日志文件路径 + - 类型：字符串 + - 默认值：`"/var/log/xxxigcc-proxy/proxy.log"` + +- `access-log-file`: 访问日志文件路径 + - 类型：字符串 + - 默认值：`"/var/log/xxxigcc-proxy/access.log"` + +### 性能配置 +- `workers`: 工作线程数 + - 类型：整数 + - 默认值：根据 CPU 核心数自动调整 + +## 源代码引用 +- 默认配置：`src/config/default_config.json` +- 配置解析：`src/config/config_parser.cpp` \ No newline at end of file diff --git a/llmdoc/reference/debian-package-structure.md b/llmdoc/reference/debian-package-structure.md new file mode 100644 index 0000000..587d698 --- /dev/null +++ b/llmdoc/reference/debian-package-structure.md @@ -0,0 +1,49 @@ +# Debian 包结构参考 + +## 目录结构 + +``` +xxxigcc-proxy_3.4.8-xg1_amd64/ +├── DEBIAN/ +│ ├── control # 包元数据 +│ ├── postinst # 安装后脚本 +│ ├── prerm # 移除前脚本 +│ └── postrm # 移除后脚本 +│ +├── opt/xxxigcc-proxy/ +│ ├── xxxigcc-proxy # 主二进制文件 +│ └── config.json # 默认配置 +│ +└── lib/systemd/system/ + └── xxxigcc-proxy.service # Systemd 服务文件 +``` + +## 关键文件说明 + +### DEBIAN/control +- 定义包的基本信息 +- 指定依赖关系 +- 提供描述性元数据 + +### 维护脚本 +- `postinst`：安装后配置 +- `prerm`：停止服务、准备卸载 +- `postrm`：清理残留文件 + +### 二进制文件 +- 位于 `/opt/xxxigcc-proxy/` +- 默认权限：`755`（可执行） + +## 依赖关系 + +必需依赖： +- `libc6` +- `libuv1` +- `libssl3` 或 `libssl1.1` +- `libhwloc15` 或 `libhwloc5` + +## 安全注意事项 + +- 严格控制文件权限 +- 使用专用用户和组 +- 最小化安装目录权限 \ No newline at end of file diff --git a/llmdoc/reference/git-conventions.md b/llmdoc/reference/git-conventions.md new file mode 100644 index 0000000..db981ee --- /dev/null +++ b/llmdoc/reference/git-conventions.md @@ -0,0 +1,43 @@ +# Git 规范指南 + +## 1. 提交信息规范 + +### 提交信息类型 +- **功能改进**：`更新`（如 "更新版本"） +- **新增特性**：`添加`（如 "添加对 Tari Solo 的支持"） +- **文档更新**：`修改`（如 "修改 README"） +- **代码清理**：`删除`（如 "删除多余行"） + +### 提交信息要求 +- 使用简体中文 +- 简洁明了，不超过 50 个字符 +- 描述具体的变更目的和影响 + +## 2. 分支管理策略 + +### 主要分支 +- `main`：稳定发布分支 + - 仅接受经过充分测试的代码 + - 直接反映生产环境状态 + +### 开发流程 +1. 从 `main` 创建功能分支 +2. 开发并完成功能 +3. 提交 Pull Request 到 `main` +4. 代码审查通过后合并 + +## 3. 标签管理 + +### 版本号命名 +- 格式：`v主版本.次版本.修订版` +- 示例：`v1.0.0` + +### 标签用途 +- 标记重要的发布版本 +- 便于版本回溯和追踪 + +## 4. 最佳实践 + +- 保持提交原子性 +- 每个提交完成一个独立的逻辑功能 +- 提交前确保代码通过基本测试 \ No newline at end of file diff --git a/llmdoc/reference/modification-checklist.md b/llmdoc/reference/modification-checklist.md new file mode 100644 index 0000000..db83f23 --- /dev/null +++ b/llmdoc/reference/modification-checklist.md @@ -0,0 +1,37 @@ +# 源代码修改清单 + +## 1. 项目重命名 +- [ ] 修改 `CMakeLists.txt` 中的项目名称 +- [ ] 替换 `project(xmrigcc-proxy)` 为 `project(xxxigcc-proxy)` + +## 2. 捐赠功能修改 +### 2.1 捐赠级别设置 +- [ ] `src/donate.h`：将 `kDefaultDonateLevel` 从 2 修改为 0 +- [ ] `src/core/config/Config_platform.h`：将 `donate-level` 从 1 修改为 0 +- [ ] `src/config.json`：将 `"donate-level"` 从 2 修改为 0 + +### 2.2 捐赠服务器地址 +- [ ] `src/net/strategies/DonateStrategy.cpp`： + - [ ] 替换 `donate.graef.in` 为 `127.0.0.1` + - [ ] 替换 `87.106.163.52` 为 `127.0.0.1` + +## 3. 版本信息定制 +- [ ] `src/version.h`： + - [ ] 替换 "xmrigcc" 为 "xxxigcc" + - [ ] 替换 "XMRigCC" 为 "XXXigCC" + +## 4. 调试配置 +- [ ] `src/config.json`：将 `"verbose"` 设置为 `true` + +## 5. 验证清单 +- [ ] 所有 sed 命令已执行 +- [ ] 捐赠功能已完全禁用 +- [ ] 项目名称已更新 +- [ ] 详细日志已启用 +- [ ] 构建通过单元测试 +- [ ] 手动功能测试完成 + +## 6. 注意事项 +- 始终在源代码版本控制下工作 +- 为修改创建单独的分支 +- 保留原始项目的基本功能架构 \ No newline at end of file