v1.0.0 发布合并回master (#52)

Co-authored-by: sundapeng <sundp@mail.zgclab.edu.cn> Co-authored-by: xuxt <xuxt@zgclab.edu.cn> Reviewed-on: #52
2025-11-25 16:00:50 +08:00
parent 9e1336d13e
commit 7430896fab
464 changed files with 45636 additions and 0 deletions
--- a/src/metric/ftp/build/README.md
+++ b/src/metric/ftp/build/README.md
@@ -0,0 +1,170 @@
+# FTP 镜像配置
+
+## 环境变量配置
+
+### FTP_BASE_PATH
+
+设置 FTP 数据的基础路径。
+
+**默认值**: `/private/argus/ftp`
+
+**用途**:
+- 共享目录路径: `${FTP_BASE_PATH}/share` (用于版本发布)
+- 配置文件存储路径: `/private/argus/etc/`
+
+### DOMAIN
+
+设置 FTP 服务的域名。
+
+**默认值**: `ftp.metric.argus.com`
+
+**用途**:
+- 容器IP记录文件: `/private/argus/etc/${DOMAIN}`
+
+### FTP_PASSWORD
+
+设置 ftpuser 用户的密码。
+
+**默认值**: `ZGClab1234!`
+
+**用途**:
+- ftpuser 用户的登录密码
+
+## 使用示例
+
+### 1. 使用默认配置
+```bash
+docker run -d \
+  --name ftp-server \
+  -p 21:21 \
+  -p 21100-21110:21100-21110 \
+  -v /host/ftp/data:/private/argus/ftp \
+  argus-metric-ftp:1.0.0
+```
+
+### 2. 自定义配置（运行时环境变量）
+```bash
+docker run -d \
+  --name ftp-server \
+  -p 21:21 \
+  -p 21100-21110:21100-21110 \
+  -e FTP_BASE_PATH=/custom/ftp/path \
+  -e DOMAIN=custom.ftp.domain.com \
+  -e FTP_PASSWORD=MySecurePassword123! \
+  -v /host/ftp/data:/custom/ftp/path \
+  argus-metric-ftp:1.0.0
+```
+
+## 目录结构
+
+容器启动后会在 `${FTP_BASE_PATH}` 下创建以下目录结构：
+
+```
+${FTP_BASE_PATH}/
+└── share/                    # FTP根目录（直接挂载）
+    └── (用户上传的文件)
+
+/private/argus/etc/
+└── ${DOMAIN}                 # 容器IP记录文件
+
+## DNS 同步到 FTP share（运行期）
+
+- 运行期最新的 DNS 列表由 bind/master 写入挂载点 `/private/argus/etc/dns.conf`。
+- FTP 容器内置 `dns-publish`（Supervised）：每 10s 比较并将该文件原子同步为 `${FTP_BASE_PATH}/share/dns.conf`，供客户端下载安装脚本直接读取。
+- 同步特性：
+  - 原子更新：写入 `${DST}.tmp` 后 `mv -f` 覆盖，避免读到半写文件。
+  - 权限：0644；属主 `${ARGUS_BUILD_UID}:${ARGUS_BUILD_GID}`。
+  - 可观测：日志 `/var/log/supervisor/dns-publish.log`。
+
+> 注：构建/发布阶段可能也会将静态 `config/dns.conf` 拷贝到 share；当 FTP 容器运行后，dns-publish 会用运行期最新文件覆盖该静态文件。
+```
+
+## vsftpd 配置说明
+
+### 核心配置参数
+
+根据README中的推荐配置，vsftpd.conf包含以下关键设置：
+
+```bash
+# 基本设置
+local_enable=YES          # 允许本地用户登录
+write_enable=YES          # 允许写操作（上传/删除/修改）
+chroot_local_user=YES     # 限制用户在自己目录中
+allow_writeable_chroot=YES # 防止 chroot 错误（重要！）
+
+# 被动模式配置
+pasv_enable=YES           # 启用被动模式
+pasv_min_port=21100       # 被动模式最小端口
+pasv_max_port=21110       # 被动模式最大端口
+
+# 用户访问控制
+userlist_enable=YES       # 启用用户列表
+userlist_file=/etc/vsftpd.userlist  # 用户列表文件
+userlist_deny=NO          # 只允许列表中的用户登录
+```
+
+### 用户管理
+
+#### 默认用户
+- **用户名**: ftpuser
+- **密码**: ZGClab1234! (可通过 FTP_PASSWORD 环境变量修改)
+- **UID**: 2133 (与prometheus用户保持一致，可通过 FTP_UID 环境变量修改)
+- **GID**: 2015 (与prometheus用户保持一致，可通过 FTP_GID 环境变量修改)
+- **主目录**: ${FTP_BASE_PATH}/share (直接指向挂载目录)
+- **Shell**: /bin/bash
+- **用户列表**: 已添加到 `/etc/vsftpd.userlist`
+
+#### 添加新用户
+```bash
+# 进入容器
+docker exec -it ftp-server bash
+
+# 添加新用户
+useradd -d ${FTP_BASE_PATH}/share/newuser -s /bin/bash newuser
+echo "newuser" >> /etc/vsftpd.userlist
+passwd newuser
+
+# 创建用户目录
+mkdir -p ${FTP_BASE_PATH}/share/newuser
+chown newuser:newuser ${FTP_BASE_PATH}/share/newuser
+```
+
+## 端口配置
+
+- **21**: FTP 控制端口
+- **20**: FTP 数据端口 (主动模式)
+- **21100-21110**: 被动模式数据端口范围
+
+### 日志文件位置
+- **vsftpd 日志**: `/var/log/vsftpd/vsftpd.log`
+- **supervisor 日志**: `/var/log/supervisor/`
+  - `supervisord.log`: supervisor 主日志
+  - `vsftpd.log`: vsftpd 标准输出
+  - `vsftpd_error.log`: vsftpd 错误输出
+
+```bash
+# 在宿主机上配置 logrotate
+cat > /etc/logrotate.d/ftp-docker << EOF
+/var/lib/docker/containers/*/ftp-server-*.log {
+    daily
+    rotate 7
+    compress
+    delaycompress
+    missingok
+    notifempty
+    copytruncate
+}
+EOF
+```
+
+### FTP连接测试
+```bash
+# 本地测试连接
+ftp localhost
+
+curl -fsS 'ftp://ftpuser:ZGClab1234!@177.177.70.200/setup.sh' -o setup.sh
+
+# root用户直接执行，非root用户需要使用sudo
+chmod +x setup.sh
+bash setup.sh --server {$域名} --user ftpuser --password 'ZGClab1234!'
+```