Merge branch 'main' of 6t7.net:cnphpbb/deploy.stack

AGENTS.md

@@ -0,0 +1,143 @@
+# AGENTS.md — deploy.stack
+
+这是一个**个人 Docker Compose Stack 集合**，用于自托管服务部署。每个子目录是一个独立可部署的服务（即一个"栈"）。仓库以中文为主，混用英文；文档文件名使用小写。
+
+## 架构与组织
+
+```
+<service>/
+  ├── stack.yml / compose.yml / <env>.stack.yml / <env>.yml   # Docker Compose 文件
+  ├── env.cfg                                                   # 环境变量（含敏感信息，应 gitignore）
+  ├── readme.md                                                 # 服务说明文档（可选）
+  └── config/                                                   # 服务配置文件（可选）
+```
+
+顶层目录按职责划分：
+
+| 目录 | 用途 |
+|------|------|
+| `<service>/`（如 `haproxy/`、`ntfy/`、`rustfs/`） | 每个可部署服务一个子目录 |
+| `builder/` | 开发容器镜像（golang、alpine、nodejs、debian）— 用于容器内编译构建 |
+| `base/` | 基础设施（cadvisor、mongo） |
+| `dbSer/` | 数据库服务栈（MySQL/Percona、Redis、PostgreSQL、MongoDB、etcd），带独立网络 |
+| `webout/` | Caddy 反向代理配置，面向外部服务 |
+| `crontab/` | 定时任务脚本（硬盘巡检、apt 更新、时间同步） |
+| `apt.list/` | 国内镜像 APT 源配置（阿里云、中科大、华为）及 Docker 安装脚本 |
+| `etc/` | 系统级配置（sysctl 内核调优） |
+| `config/` | 共享配置片段（haproxy、gitea、proxy） |
+| `shell/` | 辅助 Shell 脚本 |
+| `i2c.py/` | 树莓派 I2C OLED 显示屏脚本 |
+
+## 部署服务
+
+每个 compose 文件顶部有标准部署命令注释：
+
+```bash
+# 拉取镜像
+docker compose -p <项目名> --env-file ./<service>/env.cfg -f ./<service>/stack.yml pull
+
+# 部署
+docker compose -p <项目名> --env-file ./<service>/env.cfg -f ./<service>/stack.yml up -d
+```
+
+- `-p <项目名>` 设置 Docker Compose 项目名（通常与服务目录名一致）
+- `--env-file` 加载变量，如 `IMAGE_TAG`、`Volumes_Path`、端口、密码等
+- `-f` 指向具体的 compose YAML 文件
+
+部分服务有**多环境 compose 文件**（如 `gitea/lky-prod.yml` vs `gitea/rpi-prod.yml`、`memos/local.stack.yml` vs `memos/prod.stack.yml`、`dbSer/dbs-dev.stack.yaml` vs `dbSer/dbs.stack.yaml`）。
+
+部分服务需要**多个 env 文件**以支持多环境（如 `memos` 使用 `--env-file env.cfg --env-file db-184.cnf`）。
+
+## 命名规范
+
+| 项目 | 规范 | 说明 |
+|------|------|------|
+| 环境变量文件 | `env.cfg` | 统一使用 `.cfg` 扩展名 |
+| Compose 文件（主文件） | `stack.yml` | Docker Swarm 风格，适用于独立服务 |
+| Compose 文件（开发/构建） | `compose.yml` | Docker Compose V2 风格，用于 builder 等开发容器 |
+| Compose 文件（环境区分） | `<env>.stack.yml` | 如 `prod.stack.yml`、`local.stack.yml`、`dbs-dev.stack.yaml` |
+| Compose 文件（主机+环境） | `<host>-<env>.yml` | 如 `lky-prod.yml`、`rpi-prod.yml` |
+| Compose 文件（Harbor） | `compose.yaml` | Harbor 安装器生成的文件，**不要手动修改** |
+| 卷路径变量名 | `Volumes_Path` | 统一使用驼峰命名，**不要**使用 `Volumes_PATH` |
+
+## 关键约定
+
+### env.cfg 格式
+- `IMAGE_TAG_VER` = 版本号字符串（如 `3.3.0`）
+- `IMAGE_TAG` = 完整镜像引用，常用变量插值（如 `haproxy:${IMAGE_TAG_VER}`）
+- `Volumes_Path` = 宿主机持久化数据路径
+- 敏感值（密码、密钥）放在 `env.cfg` 中
+
+### Compose 文件顶部注释
+几乎所有 compose 文件顶部都有内联命令提示：
+```
+# path:: mkdir -pv /data/volumes/...        ← 部署前需创建的目录
+# pull:: docker compose ... pull             ← 拉取镜像命令
+# run:: / RUN:: docker compose ... up -d    ← 部署命令
+# disc:: ...                                ← 说明/警告
+```
+
+### 镜像仓库
+使用了多个私有仓库：
+- `hub.tp229.com:3500` — 主私有仓库
+- `hub.wesais.cn` — 备用私有仓库
+- `hub.node:3500` — 节点本地仓库
+- `hub.6t7.net` — 另一个私有仓库
+- 也直接使用公共镜像（如 `caddy:2.10.0`、`gitea/gitea:1.25.2-rootless`）
+
+### 宿主机卷路径
+- 生产数据：`/data/volumes/<service>/`
+- 配置数据：`/data/configs/<service>/`（Caddy、HAProxy 等配置）
+- 备份数据：`/data/backups/<service>/`
+- Harbor 特殊：`/data/harbor/`（使用 Harbor 安装器目录结构）
+
+### 时区
+所有服务设置 `TZ=Asia/Shanghai`，并只读挂载 `/etc/timezone` 和 `/etc/localtime`。
+
+### 网络模式
+- `dbSer/` 服务使用固定 IP，网络为 `DevNet`（`172.22.10.0/24`）或 `dbs-net`（`172.25.0.0/24`）
+- 需要主机网络访问的服务（如 netdata）使用 `network_mode: host`
+- 独立服务使用默认 bridge 或自定义命名网络
+
+## 构建系统（builder/）
+
+`builder/` 目录包含开发容器的 compose 文件。每个 `env.cfg` 有 `IMAGE_TAG_BASH` 和 `IMAGE_TAG_ASH` 变体。使用示例：
+
+```bash
+docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/golang/compose.yml up -d
+```
+
+自定义镜像（如 Ansible）有 `Dockerfile`，构建命令写在注释中：
+```bash
+# BUILD:: docker buildx build --platform linux/amd64 -t hub.tp229.com:3500/ansible-alpine:py3.13-rootless .
+```
+
+## 定时任务（crontab/）
+
+| 文件 | 建议周期 | 用途 |
+|------|----------|------|
+| `smartctl.job` | 手动/外部 cron | megaraid 控制器原始 smartctl 输出 |
+| `disk_inspection.py` | 每天 02:00 | 解析 SMART 报告 → Markdown + MCP 提交 |
+| `autoApt.job` | 每周一 01:05 | `apt update && upgrade && autoremove` |
+| `timeUpdate.job` | 每天 01:00 | NTP 时间同步（ntpdate 或 timedatectl） |
+
+所有 `.job` 文件需要 `chmod +x`（由 `shell/up.bash` 处理）。
+
+## 重要注意事项
+
+- **Harbor 是特殊情况**：通过官方 Harbor 安装器部署，不是简单的 compose 文件。`harbor/compose.yaml` 是 `./prepare` 生成的输出文件，非手写，不要修改。
+- **Gitea 备份**：`gitea/backup.job` 在 rsync 前停止容器、完成后重启——不适用于零停机场景。
+- **端口冲突**：多个服务默认使用相同端口（如 Grafana 和 Gitea 都默认 3000，多个服务默认 8080）。通过 env 文件或不同 compose 文件区分环境。
+- **私有仓库镜像**：很多 `IMAGE_TAG` 引用私有仓库（`hub.tp229.com:3500`、`hub.wesais.cn`），无访问权限时无法拉取。
+- **国内镜像源**：Dockerfile 和 apt 配置默认使用国内 CDN 镜像（中科大、阿里云、华为），部署在其他地区需修改。
+- **Portainer Docker 兼容性**：Portainer CE LTS < 2.36.0 不兼容 Docker >= 29.0.0，需设置 `DOCKER_MIN_API_VERSION=1.24`。详见 `portainer-ce/readme.md`。
+- **i2c.py 需要硬件**：OLED 显示脚本需要树莓派 I2C 硬件、`adafruit_ssd1306` 库和中文字体（`fonts-wqy-microhei`）。
+
+## 系统配置（etc/）
+
+`etc/sysctl.conf` 包含内核调优参数：
+- 桥接 netfilter（容器需要）
+- TCP 性能调优（keepalive、TIME_WAIT、窗口缩放、Fast Open）
+- 连接队列大小（somaxconn、syn backlog）
+- 内存管理（swappiness、脏页阈值）
+- 安全加固（ICMP 重定向拒绝、反向路径过滤、kptr_restrict）

adminer/readme.md

@@ -0,0 +1,42 @@
+# Adminer 部署说明
+
+[Adminer](https://www.adminer.org/) 是一个轻量级的数据库管理工具，支持 MySQL、PostgreSQL、SQLite、MS SQL、Oracle 等多种数据库，单文件 PHP 应用，适合日常数据库运维操作。
+
+## 目录结构
+
+| 文件 | 说明 |
+|------|------|
+| `stack.yml` | Docker Compose 部署配置 |
+| `env.cfg` | 环境变量（镜像版本） |
+
+## 部署命令
+
+```bash
+# 拉取镜像
+docker compose -p adminer --env-file ./adminer/env.cfg -f ./adminer/stack.yml pull
+
+# 启动服务
+docker compose -p adminer --env-file ./adminer/env.cfg -f ./adminer/stack.yml up -d
+
+# 停止服务
+docker compose -p adminer --env-file ./adminer/env.cfg -f ./adminer/stack.yml down
+```
+
+## 环境变量说明
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `IMAGE_TAG_VER` | Adminer 镜像版本 | `5.4.2` |
+| `IMAGE_TAG` | 完整镜像标签 | `adminer:5.4.2` |
+| `Volumes_Path` | 数据卷宿主机路径 | `/data/volumes/adminer` |
+
+## 访问服务
+
+- 默认端口：`8080`
+- 访问地址：`http://<主机IP>:8080`
+
+## 注意事项
+
+- Adminer 本身无持久化数据，容器重建不影响使用
+- 连接数据库时使用数据库容器的服务名或内网 IP，而非 localhost
+- 建议仅在内部网络使用，不要直接暴露到公网

adminer/stack.yml

@@ -0,0 +1,15 @@
+# pull:: docker compose -p adminer --env-file ./adminer/env.cfg -f ./adminer/stack.yml pull
+# run:: docker compose -p adminer --env-file ./adminer/env.cfg -f ./adminer/stack.yml up -d
+
+services:
+  adminer:
+    image: ${IMAGE_TAG}
+    container_name: adminer
+    restart: unless-stopped
+    ports:
+      - '8080:8080'
+    environment:
+      - TZ=Asia/Shanghai
+    volumes:
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro

ansible/compose.yml

@@ -1,4 +1,4 @@
-# DEPLOY:: docker compose -p base --env-file ./ansible/env.cfg -f ./ansible/docker-compose.yml up -d
+# DEPLOY:: docker compose -p base --env-file ./ansible/env.cfg -f ./ansible/compose.yml up -d
 services:
   ansible:
     image: ${IMAGE_TAG}

builder/alpine/env.cnf

@@ -1 +0,0 @@
-IMAGE_TAG=alpine:3

builder/debian/env.cnf

@@ -1 +0,0 @@
-IMAGE_TAG=debian:13

builder/golang/env.cnf

@@ -1,3 +0,0 @@
-IMAGE_TAG_BASH=golang:1.25.0-trixie
-IMAGE_TAG_ASH=golang:1.25.0-alpine
-Volumes_Path=/data/volumes

crush.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://charm.land/crush.json",
+  "options": {
+    "context_paths": ["."]
+  }
+}

dbSer/redis/redis.stack.yml

@@ -9,7 +9,7 @@ services:
       - '6379:6379'
     command: redis-server --appendonly yes --requirepass ${REDIS_PASSWORD} 
     volumes:
-      - '${Volumes_PATH}/redis_data:/data'
+      - '${Volumes_Path}/redis_data:/data'
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
     environment:

dbSer/redis/valkey.stack.yml

@@ -9,7 +9,7 @@ services:
       - '6379:6379'
     command: valkey-server --appendonly yes --requirepass ${REDIS_PASSWORD}
     volumes:
-      - '${Volumes_PATH}/valkey_data:/data'
+      - '${Volumes_Path}/valkey_data:/data'
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
     environment:

domain-admin/stack.yml

@@ -3,8 +3,8 @@
 services:
   domain-admin:
     volumes:
-      - '${Volumes_PATH}/database:/app/database'
-      - '${Volumes_PATH}/logs:/app/logs'
+      - '${Volumes_Path}/database:/app/database'
+      - '${Volumes_Path}/logs:/app/logs'
     ports:
       - '9800:8000'
     environment:

gitea/lky-prod.yml

@@ -17,8 +17,8 @@ services:
     volumes:
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
-      - ${Volumes_PATH}/data:/var/lib/gitea
-      - ${Volumes_PATH}/config:/etc/gitea
+      - ${Volumes_Path}/data:/var/lib/gitea
+      - ${Volumes_Path}/config:/etc/gitea
     ports:
       - 3000:3000
       - ${LAY_SSH_HOST_PORT}:2222

gitea/rpi-prod.yml

@@ -17,8 +17,8 @@ services:
     volumes:
       - /etc/timezone:/etc/timezone:ro
       - /etc/localtime:/etc/localtime:ro
-      - ${Volumes_PATH}/data:/var/lib/gitea
-      - ${Volumes_PATH}/config:/etc/gitea
+      - ${Volumes_Path}/data:/var/lib/gitea
+      - ${Volumes_Path}/config:/etc/gitea
     ports:
       - 3000:3000
       - ${SSH_HOST_PORT}:2222

hub-registry/env.cnf

@@ -1,2 +0,0 @@
-IMAGE_TAG=hub.tp229.com:3500/registry:3.0
-UI_IMAGE_TAG=hub.tp229.com:3500/cnphpbb/registry-ui:latest

hub-registry/stack.yml

@@ -1,4 +1,4 @@
-# run:: docker compose -p hub-registry --env-file ./hub-registry/env.cfg -f ./hub-registry/stack.yaml up -d
+# run:: docker compose -p hub-registry --env-file ./hub-registry/env.cfg -f ./hub-registry/stack.yml up -d
 
 services:
   registry:

searxng/stack.yml

@@ -12,7 +12,7 @@ services:
     networks:
       - searxng
     volumes:
-      -  ${Volumes_PATH}/redis-data:/data
+      -  ${Volumes_Path}/redis-data:/data
 
   searxng:
     image: ${SearXNG_TAG}
@@ -28,8 +28,8 @@ services:
     networks:
       - searxng
     volumes:
-      - ${Volumes_PATH}/etc-searxng:/etc/searxng:rw
-      - ${Volumes_PATH}/searxng-data:/var/cache/searxng:rw
+      - ${Volumes_Path}/etc-searxng:/etc/searxng:rw
+      - ${Volumes_Path}/searxng-data:/var/cache/searxng:rw
 
 networks:
   searxng: