# paas-tools

**Repository Path**: nine-piece/paas-tools

## Basic Information

- **Project Name**: paas-tools
- **Description**: 用docker部署基础环境的集合项目
- **Primary Language**: Shell
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-17
- **Last Updated**: 2025-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Frappe 后端中间件 Docker 部署指南

## 概述
本目录包含 Frappe 应用所需的 Redis 和 MariaDB 中间件的 Docker Compose 配置，用于快速搭建独立的后端支持环境。

## 组件说明
- **MariaDB**: 关系型数据库服务，用于存储 Frappe 应用数据
- **Redis**: 内存数据存储，用于缓存和消息队列

## 环境要求
- Docker Engine (20.10+)
- Docker Compose (v2+)

## 快速开始

### 1. 环境配置
```bash
# 进入工具目录
cd /Users/luwu/workspace/erp/freapp/frappe-bench/tools

# （可选）修改环境变量
vi .env
```

### 2. 启动服务

支持通过Docker Compose Profiles选择性启动模块：

```bash
# 启动默认服务（MariaDB + Redis）
docker-compose up -d

# 启动指定模块（例如：仅PostgreSQL）
docker-compose --profile postgresql up -d

# 启动多个模块（例如：MariaDB + Redis + Celery）
docker-compose --profile mariadb --profile redis --profile celery up -d
```

可用模块Profiles及依赖关系：
- `mariadb`: MariaDB数据库（独立模块）
- `postgresql`: PostgreSQL数据库（独立模块）
- `redis`: Redis缓存/队列（独立模块）
- `celery`: Celery任务队列（依赖Redis模块）

### 模块组合示例
```bash
# 基础数据库+缓存（MariaDB+Redis）
docker-compose --profile mariadb --profile redis up -d

# 完整任务队列环境（Redis+Celery）
docker-compose --profile redis --profile celery up -d

# 多数据库环境（MariaDB+PostgreSQL）
docker-compose --profile mariadb --profile postgresql up -d


### 3. 验证服务状态
```bash
docker-compose ps
# 检查服务健康状态
docker-compose exec mariadb mysqladmin ping -u root -p$MYSQL_ROOT_PASSWORD
docker-compose exec redis redis-cli ping
```

### 4. 停止服务
```bash
docker-compose down
# 停止并删除数据卷（谨慎操作！）
docker-compose down -v
```

## 配置说明

### 环境变量 (.env)
所有敏感配置通过环境变量管理，主要参数包括：
- 数据库 root 密码、数据库名、用户名及密码
- Redis 密码
- 端口映射配置

### 服务配置
- **MariaDB**: 配置文件位于 `mariadb/conf.d/my.cnf`，包含 Frappe 推荐的 MySQL 配置
  - **Logging**:
    - **Log Directory**: `./mariadb/logs`
    - **Log Types**: General queries, slow queries, and error logs
    - **Configuration**: Log settings are defined in `./mariadb/conf.d/my.cnf`
      - General log: `mariadb-general.log`
      - Slow query log: `mariadb-slow.log` (queries taking >2 seconds)
      - Error log: `mariadb-error.log`
- **PostgreSQL**: 配置文件位于 `postgresql/conf.d`，使用 `postgres:14-alpine` 镜像，数据存储在 `./postgresql/data` 卷，端口映射 5432。环境变量 `POSTGRES_DB`、`POSTGRES_USER`、`POSTGRES_PASSWORD` 在 `.env` 中配置
  - **Logging**:
    - **Log Directory**: `./postgresql/logs`
    - **Log Files**: Daily rotated logs in format `postgresql-YYYY-MM-DD.log`
    - **Configuration**: Log settings are defined in `./postgresql/conf.d/postgresql.conf`
      - Logs all statements
      - Logs slow queries (>2 seconds)
      - Verbose error logging
- **Redis**: 配置文件位于 `redis/redis.conf`，包含内存限制、持久化策略等设置
  - **Logging**:
    - **Log Directory**: `./redis/logs`
    - **Log File**: `redis.log`
    - **Configuration**: Log settings are defined in `./redis/redis.conf`

  - **Celery+Redis Task Queue**: 分布式任务队列，使用Redis作为消息代理和结果存储
    - **组件**: celery-worker(任务执行)、celery-flower(监控面板)
    - **配置文件**: `./celery/conf.d/celeryconfig.py`
    - **队列优先级**: high(高)、default(中)、low(低)三级队列
    - **Logging**: 
      - **日志目录**: `./celery/logs`
      - **Docker日志**: 自动轮转JSON日志(单文件最大10MB，保留5个文件)
    - **监控访问**: Flower面板 `http://localhost:5555`
    - **任务示例**: 示例代码位于 `./celery/examples/task_examples.py`
      ```bash
      # 运行任务示例
      cd ./celery/examples
      python task_examples.py
      ```
      示例包含高/中/低优先级任务的定义与调用，以及结果处理逻辑。
    - **环境变量**: 
      - `REDIS_URL`: Redis连接地址
      - `CELERY_CONFIG_MODULE`: 配置模块路径

## 数据持久化
- MariaDB 数据存储在 `mariadb-data` 卷中
- Redis 数据存储在 `redis-data` 卷中
- 卷数据默认不会随容器删除而丢失

## 日志查看
```bash
# MariaDB 日志
docker-compose logs -f mariadb

# Redis 日志
docker-compose logs -f redis
```

## 注意事项
- 生产环境中应修改默认密码并加强安全配置
- 根据服务器资源调整内存限制和连接数
- 定期备份数据卷或使用外部备份服务

## Celery+Redis 任务队列

### 组件说明
- **celery-worker**: 任务执行服务，基于`python:3.10-slim`镜像构建，负责处理队列中的任务
- **celery-flower**: 任务监控面板，提供任务状态可视化界面

### 依赖管理
Celery Worker依赖项通过`./celery/requirements.txt`管理，包含:
```
celery==5.3.6
redis==4.5.5
python-dotenv==1.0.0
```

### 配置文件
- 主配置: `./celery/conf.d/celeryconfig.py`
- 环境变量配置: 支持通过环境变量覆盖默认配置

### 环境变量说明
| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| REDIS_URL | Redis服务地址 (必填) | redis://redis:6379 |
| CELERY_BROKER_DB | Broker数据库编号 | 0 |
| CELERY_BACKEND_DB | Backend数据库编号 | 1 |
| CELERY_TASK_TIME_LIMIT | 任务超时时间(秒) | 30 |
| CELERY_TASK_MAX_RETRIES | 最大重试次数 | 3 |
| CELERY_RETRY_BACKOFF | 重试间隔增长系数 | 5 |

### 队列优先级
- **high**: 高优先级队列(如支付处理)
- **default**: 普通优先级队列(如报表生成)
- **low**: 低优先级队列(如批量通知)

### 跨服务器调用示例
示例代码位于 `./celery/examples/task_examples.py`，支持从外部服务器调用Celery任务队列：

```bash
# 配置环境变量
export REDIS_URL=redis://远程服务器IP:6379

# 运行示例代码
python ./celery/examples/task_examples.py
```

### 监控访问
Flower监控面板: `http://localhost:5555`


#### MySQL服务

MySQL服务已配置独立部署，使用3307端口以避免与MariaDB冲突：

```bash
# 启动MySQL服务
cd tools/mysql && docker-compose up -d

# 查看服务状态
cd tools/mysql && docker-compose ps

# 停止服务
cd tools/mysql && docker-compose down
```

默认配置包含UTF8mb4字符集支持和性能优化参数，配置文件位于`<mcfile name="my.cnf" path="/Users/luwu/workspace/erp/freapp/frappe-bench/tools/mysql/conf.d/my.cnf"></mcfile>`。


## 服务管理脚本

为简化多模块操作，已提供统一的服务管理脚本 `<mcfile name="service-manager.sh" path="/Users/luwu/workspace/erp/freapp/frappe-bench/tools/service-manager.sh"></mcfile>`，支持对所有模块或单个模块执行启动、停止、重启、状态查看和日志查看操作。

### 使用方法
```bash
# 基本语法
./service-manager.sh [命令] [模块名|all]

# 启动所有模块
./service-manager.sh start all

# 停止指定模块
./service-manager.sh stop mysql

# 重启指定模块
./service-manager.sh restart celery

# 查看所有模块状态
./service-manager.sh status all

# 查看模块日志（显示最后100行）
./service-manager.sh logs redis
```

### 支持的命令
- `start`: 启动服务
- `stop`: 停止服务
- `restart`: 重启服务
- `status`: 查看服务状态
- `logs`: 查看服务日志
- `help`: 显示帮助信息

### 支持的模块
- `celery`: Celery Worker服务
- `redis`: Redis缓存服务
- `mariadb`: MariaDB数据库服务
- `postgresql`: PostgreSQL数据库服务
- `mysql`: MySQL数据库服务
- `all`: 操作所有模块