ParkWhiz Rails 应用基础镜像文档

1. 镜像概述

1.1 主要用途

本镜像为 ParkWhiz Ruby on Rails 应用的专用基础镜像，基于 Alpine Linux 构建，预配置 Ruby、Rails、Phusion Passenger 和 Nokogiri 等核心依赖。旨在简化 ParkWhiz 内部 Ruby on Rails 服务器容器的部署流程，提供开箱即用的 Rails 运行环境。

2. 核心功能与特性

2.1 基础环境

• 轻量级底座：基于 Alpine Linux，具备体积小（通常比 Debian 基础镜像小 50%+）、启动快、资源占用低的特点。
• 预构建依赖：集成指定版本的 Ruby 和 Rails（版本信息需参考镜像标签或***说明），避免手动编译安装耗时。

2.2 应用服务集成

• Phusion Passenger：内置 Phusion Passenger 应用服务器，支持 Rails 应用的高效运行与进程管理，兼容生产环境需求。
• Nokogiri 预安装：预编译并安装 Nokogiri（XML/HTML 解析库），解决其在 Alpine 环境下依赖 libxml2/libxslt 的编译难题。

3. 使用场景与适用范围

3.1 适用场景

• ParkWhiz 内部 Ruby on Rails 应用的容器化部署（开发、测试、生产环境通用）。
• 需要快速搭建 Rails 服务器环境，减少基础依赖配置工作量的场景。

3.2 限制

• 专为 ParkWhiz 应用设计，非通用 Rails 基础镜像，外部应用使用需评估兼容性。

4. 使用方法与配置说明

4.1 前置条件

• 本地已安装 Docker 或 Docker Compose。
• 需准备 Rails 应用代码（目录结构符合 Rails 标准，包含 Gemfile、config.ru 等）。

4.2 快速启动（docker run）

命令示例

docker run -d \
  --name parkwhiz-rails-app \
  -v /path/to/local/rails/app:/app  # 挂载本地 Rails 应用代码到容器内 /app 目录  
  -e RAILS_ENV=production  # 设置 Rails 环境（开发环境可改为 development）  
  -p 3000:3000  # 暴露容器 3000 端口到主机  
  parkwhiz/rails-base:latest  # 镜像名称（需替换为实际镜像名及标签）

说明

• /path/to/local/rails/app：本地 Rails 应用代码的绝对路径，容器会读取该目录下的应用文件。
• 容器启动后，Passenger 会自动检测 /app 目录下的 Rails 应用，并通过 passenger start 启动服务，默认监听 3000 端口。

4.3 Docker Compose 配置

示例配置（docker-compose.yml）

version: '3.8'

services:
  rails-app:
    image: parkwhiz/rails-base:latest  # 基础镜像
    container_name: parkwhiz-rails-app
    restart: always  # 生产环境建议设置为 always，确保服务异常退出后自动重启
    volumes:
      - ./rails-app:/app  # 挂载当前目录下的 rails-app 目录到容器 /app
      - bundle:/usr/local/bundle  # 持久化 RubyGems 依赖（避免重复安装）
    environment:
      - RAILS_ENV=production
      - DATABASE_URL=postgres://user:password@db:5432/app_db  # 数据库连接地址（示例）
    ports:
      - "3000:3000"
    depends_on:
      - db  # 若依赖数据库，需定义 db 服务（如下）

  # 数据库服务示例（PostgreSQL）
  db:
    image: postgres:14-alpine
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=app_db

volumes:
  bundle:  # 持久化 RubyGems 依赖
  postgres-data:  # 持久化数据库数据

启动命令

docker-compose up -d  # 后台启动服务

4.4 配置参数

4.4.1 环境变量

4.4.2 自定义配置

• Ruby/Rails 版本：镜像中预配置指定版本的 Ruby 和 Rails，具体版本需通过镜像标签确认（如 parkwhiz/rails-base:ruby3.2-rails7.0），不支持运行时修改。
• Passenger 配置：可通过挂载应用内的 config/passenger.conf 文件覆盖默认配置（如工作进程数、超时时间等）。

5. 注意事项

• 权限问题：容器内 Rails 应用目录（/app）默认权限为 root，若本地开发需修改文件，可通过 docker run -u $(id -u):$(id -g) 映射当前用户 UID/GID 避免权限冲突。
• 依赖更新：若应用 Gemfile 变更，需重新构建镜像或进入容器执行 bundle install。
• 日志查看：通过 docker logs parkwhiz-rails-app 查看应用及 Passenger 运行日志。