forked from DevOps/deploy.stack
cnphpbb
60d30afaff
1. 将所有环境变量中的Volumes_PATH统一改为Volumes_Path 2. 把旧的.env.cnf文件重命名为.env.cfg 3. 将compose.yaml文件统一替换为stack.yml/compose.yml格式 4. 删除冗余的旧版compose配置文件
144 lines
7.1 KiB
Markdown
144 lines
7.1 KiB
Markdown
# 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）
|