macos-tools/shared

基础组件部署方案

统一部署所有公共基础服务，供多个项目共用的企业级 DevOps 基础设施。

🏗️ 架构概览

核心服务

• 数据库层: PostgreSQL 16 + MySQL 8
• 缓存层: Redis 7
• 代码仓库: Gitea 1.22
• 镜像仓库: Harbor 2.11
• 监控层: Prometheus + Grafana + cAdvisor
• 网关反代: Traefik v3.1

网络架构

• 所有服务运行在同一个 Docker 网络 core 内
• 各项目通过网络名访问数据库和缓存（非 localhost）
• 端口统一使用 2 开头，避免冲突

📁 目录结构

/srv/shared/
├── docker-compose.yml          # 主配置文件
├── .env.example               # 环境变量模板
├── .env                       # 实际环境变量配置
├── data/                      # 数据目录
│   ├── postgres/             # PostgreSQL 数据
│   ├── mysql/                # MySQL 数据
│   ├── redis/                # Redis 数据
│   ├── gitea/                # Gitea 数据
│   ├── harbor/               # Harbor 数据
│   ├── prometheus/           # Prometheus 数据
│   └── grafana/              # Grafana 数据
├── acme/                     # Traefik SSL证书
├── prometheus/
│   └── prometheus.yml        # Prometheus 配置
├── bin/
│   ├── up.sh                 # 一键启动脚本
│   └── down.sh               # 一键停止脚本
└── README.md                 # 本文档

🚀 快速开始

1. 环境准备

# 确保 Docker 和 Docker Compose 已安装
docker --version
docker compose version

# 复制环境变量配置
cp .env.example .env

# 根据需要修改配置
vim .env

2. 一键启动

# 进入项目目录
cd /Users/brunogao/work/codes/tools/macos/shared

# 启动所有服务
./bin/up.sh

3. 验证服务

# 检查服务状态
docker compose ps

# 查看服务日志
docker compose logs -f

4. 停止服务

# 仅停止服务
./bin/down.sh

# 停止服务并清理数据
./bin/down.sh --cleanup

🌐 访问地址

域名访问 (推荐)

需要在 /etc/hosts 中添加解析：

127.0.0.1 gitea.local.lan harbor.local.lan grafana.local.lan traefik.local.lan prometheus.local.lan cadvisor.local.lan

服务	域名地址	端口访问	用户名	密码
Traefik	http://traefik.local.lan	http://localhost:28080	-	-
Gitea	http://gitea.local.lan	http://localhost:23000	-	自设
Harbor	http://harbor.local.lan	http://localhost:28081	admin	自设
Grafana	http://grafana.local.lan	http://localhost:23001	admin	admin
Prometheus	http://prometheus.local.lan	http://localhost:29090	-	-
cAdvisor	http://cadvisor.local.lan	http://localhost:28089	-	-

🔗 数据库连接

PostgreSQL

• 连接地址: postgres:5432 (容器内) / localhost:25432 (宿主机)
• 用户名: postgres
• 密码: postgres123
• 数据库: postgres

MySQL

• 连接地址: mysql:3306 (容器内) / localhost:23306 (宿主机)
• 用户名: mysql
• 密码: mysql123
• 数据库: mysql

Redis

• 连接地址: redis:6379 (容器内) / localhost:26379 (宿主机)
• 密码: redis123

📦 项目接入指南

1. 加入核心网络

在项目的 docker-compose.yml 中添加：

networks:
  core:
    external: true

services:
  your-app:
    networks: [core]
    # ... 其他配置

2. 配置数据库连接

在项目的 .env 文件中配置：

# PostgreSQL
PG_HOST=postgres
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=postgres123
PG_DB=your_database

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=redis123

# MySQL (如需要)
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_USER=mysql
MYSQL_PASSWORD=mysql123
MYSQL_DB=your_database

3. 示例项目配置

version: "3.8"

networks:
  core:
    external: true

services:
  app:
    image: your-app:latest
    environment:
      - DATABASE_URL=postgres://postgres:postgres123@postgres:5432/your_app
      - REDIS_URL=redis://:redis123@redis:6379/0
    networks: [core]
    depends_on:
      - postgres
      - redis

🔧 监控配置

Prometheus 指标收集

配置文件位置: prometheus/prometheus.yml

当前监控目标：

• Traefik 网关指标
• cAdvisor 容器指标
• PostgreSQL 指标
• Redis 指标

Grafana 仪表板

• 访问地址: http://grafana.local.lan:23001
• 默认用户名/密码: admin/admin
• 可配置自定义仪表板和数据源

🔒 安全配置

密钥管理

• 首次运行时自动生成随机密钥
• 建议定期更换生产环境密钥
• 密钥存储在 .env 文件中

网络安全

• 所有服务都在内部网络 core 中运行
• 仅暴露必要的端口到宿主机
• Traefik 提供统一的 HTTPS 入口

🛠️ 运维管理

备份数据

# 备份 PostgreSQL
docker exec postgres pg_dump -U postgres postgres > backup.sql

# 备份 MySQL
docker exec mysql mysqldump -u mysql -pmysql123 mysql > mysql_backup.sql

# 备份 Redis
docker exec redis redis-cli --rdb redis_backup.rdb

恢复数据

# 恢复 PostgreSQL
docker exec -i postgres psql -U postgres postgres < backup.sql

# 恢复 MySQL
docker exec -i mysql mysql -u mysql -pmysql123 mysql < mysql_backup.sql

# 恢复 Redis
docker cp redis_backup.rdb redis:/data/dump.rdb
docker restart redis

日志管理

# 查看所有服务日志
docker compose logs

# 查看特定服务日志
docker compose logs postgres
docker compose logs -f redis  # 实时跟踪

# 清理日志
docker compose logs --no-log-prefix > /dev/null 2>&1

🔍 故障排除

常见问题

1. 端口冲突

   • 所有端口已配置为 2 开头，避免冲突
   • 如仍有冲突，请检查端口占用：lsof -i :25432

2. 权限问题

   • 确保 Docker 有足够权限
   • 检查数据目录权限

3. 内存不足

   • 监控系统内存使用
   • 调整 Docker 内存限制

4. 网络连接问题

   • 检查 core 网络状态：docker network inspect core
   • 确保项目正确加入网络

健康检查

# 检查服务健康状态
docker compose ps

# 测试数据库连接
docker exec postgres pg_isready -U postgres
docker exec redis redis-cli ping

# 检查网络连通性
docker exec postgres ping redis

📈 性能优化

生产环境建议

1. 资源配置: 根据负载调整容器资源限制
2. 存储优化: 使用 SSD 存储，配置适当的存储驱动
3. 网络优化: 配置合适的 MTU，使用高性能网络驱动
4. 监控告警: 配置 Prometheus 告警规则
5. 备份策略: 制定定期备份和恢复演练计划

扩展方向

• Traefik: 接入 Cloudflare DNS 自动申请证书
• Grafana: 添加 Alertmanager、NodeExporter
• Harbor: 配置 robot 账号供 CI/CD
• Gitea: 连接 GitLab Runner 或 Gitea Actions
• PostgreSQL: 扩展 PGAdmin 管理界面
• Redis: 支持多数据库隔离（DB0~15）

📞 支持

如有问题，请：

1. 检查日志文件排查问题
2. 查看本文档故障排除部分
3. 提交 Issue 到项目仓库

---

注意: 这是企业级基础设施，请在生产环境中充分测试并配置适当的安全措施。