Files

cnphpbb 60d30afaff refactor: 统一环境变量命名并整理配置文件格式

1. 将所有环境变量中的Volumes_PATH统一改为Volumes_Path
2. 把旧的.env.cnf文件重命名为.env.cfg
3. 将compose.yaml文件统一替换为stack.yml/compose.yml格式
4. 删除冗余的旧版compose配置文件

2026-05-17 00:38:41 +08:00

7.1 KiB

Raw Blame History

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 文件顶部有标准部署命令注释：

# 拉取镜像
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 变体。使用示例：

docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/golang/compose.yml up -d

自定义镜像（如 Ansible）有 Dockerfile，构建命令写在注释中：

# 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）

7.1 KiB Raw Blame History Unescape Escape