基于 Nginx + Passenger 完整部署 Redmine 项目管理系统（生产环境稳定版）

想睡就睡
55 阅读6分钟

基于 Nginx + Passenger 完整部署 Redmine 项目管理系统（生产环境稳定版）

引言

本教程详细指导你在本地环境中搭建并使用 Redmine。Redmine 是一个开源的项目管理平台，基于 Ruby on Rails，支持问题跟踪、论坛、Wiki、Gantt 图和版本控制集成。它适合团队协作、bug 跟踪和项目规划。我们将使用 Ubuntu Linux 系统（推荐 22.04 LTS）作为示例，通过手动安装方式进行搭建。

注意：本教程假设你有基本的 Linux 命令和 Ruby 知识。

系统要求

  • 操作系统：Ubuntu 20.04 或更高版本（其他 Linux 发行版需调整）。
  • 硬件：至少 2GB RAM、1 核 CPU、10GB 可用磁盘空间（推荐 4GB RAM）。
  • 网络：静态 IP（可选）；端口 3000（默认）或 80/443（使用 Nginx）。
  • 软件：Ruby 2.7+、Rails 6.1+、数据库（如 MySQL 或 PostgreSQL）、ImageMagick（附件处理）。

如果不符合要求，Redmine 可能运行缓慢。

安装步骤

我们分步进行安装和配置。以下流程图概述整个过程：
准备系统 安装 Ruby 和 Rails 安装数据库 下载和配置 Redmine 启动 Redmine 初始设置和使用 测试和优化

步骤 1: 更新系统和安装依赖
  1. 打开终端，运行：
sudo apt update
sudo apt upgrade -y
  1. 安装基本依赖：
sudo apt install -y build-essential libssl-dev libreadline-dev zlib1g-dev libyaml-dev libxml2-dev libxslt1-dev libcurl4-openssl-dev libffi-dev git imagemagick
步骤 2: 安装 Ruby 和 Rails

使用 rbenv（推荐）管理 Ruby 版本。

  1. 安装 rbenv：
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
  1. 安装 Ruby（例如 3.0.0，检查 Redmine 兼容版本）：
rbenv install 3.0.0
rbenv global 3.0.0
  1. 安装 Rails 和 Bundler：
gem install bundler
gem install rails -v 6.1.7  # 检查 Redmine 要求的版本
步骤 3: 安装数据库

我们使用 MySQL 为例（PostgreSQL 类似）。

  1. 安装 MySQL：
sudo apt install -y mysql-server mysql-client libmysqlclient-dev
sudo mysql_secure_installation  # 安全配置
  1. 创建数据库和用户：
sudo mysql -u root -p
  1. 在 MySQL shell 中：
CREATE DATABASE redmine CHARACTER SET utf8mb4;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
FLUSH PRIVILEGES;
EXIT;

数据库设置序列图：
User MySQL 登录 root 授权 创建数据库 redmine 创建用户 redmine 授予权限 完成 User MySQL

步骤 4: 下载和配置 Redmine
  1. 下载 Redmine（最新稳定版，从 redmine.org）：
wget https://www.redmine.org/releases/redmine-5.1.3.tar.gz  # 检查最新版本
tar xvf redmine-5.1.3.tar.gz
mv redmine-5.1.3 /opt/redmine
cd /opt/redmine
  1. 配置数据库：
    • 复制模板：cp config/database.yml.example config/database.yml
  1. 编辑 nano config/database.yml，在 production 部分设置：
production:
  adapter: mysql2
  database: redmine
  host: localhost
  username: redmine
  password: "your_password"
  encoding: utf8mb4
  1. 安装 gem 依赖：
bundle config set --local without 'development test'
bundle install
  1. 生成密钥并迁移数据库：
bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake redmine:load_default_data REDMINE_LANG=en  # 或 zh 为中文
步骤 5: 启动 Redmine
  1. 启动内置服务器（开发用）：
bundle exec rails server webrick -e production
  1. 在浏览器访问 http://localhost:3000（或你的 IP:3000）。

对于生产，安装 Passenger + Nginx（见优化部分）。

步骤 6: 初始设置和使用
  1. 登录：默认 admin/admin，立即更改密码（Administration > Users）。
  2. 创建项目：Projects > New project，设置名称、标识符。
  3. 添加用户：Administration > Users > New user，分配角色。
  4. 使用功能 ：
    • 问题跟踪：Issues > New issue。
    • Wiki：启用模块，添加页面。
    • 集成 SCM（如 Git）：在项目设置中配置仓库。
    • Gantt 图：Projects > Gantt。

使用流程图：
登录 创建项目 添加用户/角色 创建 Issue 使用 Wiki/论坛 查看 Gantt/日历

步骤 7：基于 Nginx + Passenger启动 Redmine
  1. 生产服务器：安装 Nginx 和 Passenger：
sudo apt install -y nginx
gem install passenger
  1. 配置 Nginx 指向 Redmine。
passenger-install-nginx-module
  1. 检查核心环境是否正常
# 1. 检查Ruby版本（必须≥3.0.0，低于则升级Ruby）
ruby -v
# 2. 检查Passenger版本（正常输出版本即安装成功）
passenger -v
# 3. 检查Nginx是否集成Passenger模块（关键！必须看到passenger相关配置）
/opt/nginx/sbin/nginx -V

✅ 正常标识：nginx -V 的输出中包含 --add-module=xxx/passenger-xxx/ext/nginx

  1. 明确本次部署的核心目录约定（固定，全程统一）
  • Nginx 根目录：/opt/nginx (编译安装固定路径)
  • Redmine 安装目录：/opt/redmine (行业规范，权限友好，推荐此路径)
  • Redmine 运行环境：production 生产环境（关闭调试、优化性能）
步骤 8：创建必要目录并授权（解决文件写入权限问题）
# 创建redmine运行所需的临时目录
mkdir -p tmp tmp/pdf public/plugin_assets log files

# 赋予读写权限（Passenger运行需要）
chmod -R 755 /var/www/redmine
chmod -R 775 tmp log files public/plugin_assets
步骤 9：核心配置 - Nginx + Passenger 整合 Redmine（最关键）
核心原理：

Passenger 是 Nginx 的嵌入式模块，所有 Ruby/Rails 应用（包括Redmine）的 Nginx 配置规则都是固定的：必须将 root 指向应用的 public 目录，Passenger 会自动识别并托管 Ruby 应用，无需启动任何 Redmine 进程，Nginx启动则Redmine启动，Nginx重启则Redmine重启，这是最省心的部署方式！

  1. 编辑 Nginx 主配置文件
vim /opt/nginx/conf/nginx.conf
  1. 关键检查：确认配置文件顶部已存在 Passenger 配置

执行 passenger-install-nginx-module 时，脚本会自动写入以下配置到 nginx.conf 顶部，无需手动添加，检查是否存在即可，存在则跳过这一步：

passenger_root /usr/local/lib/ruby/gems/3.2.0/gems/passenger-6.0.20; # 你的passenger路径
passenger_ruby /usr/local/bin/ruby; # 你的ruby可执行路径
passenger_instance_registry_dir /tmp;

如缺失：执行 passenger-config --root 可获取 passenger_root 路径，手动添加即可。

  1. 核心修改：配置 Redmine 的 Server 站点块

在 nginx.conf 的 http{} 内部，注释掉默认的 server 块（原来的80端口默认站点），然后添加以下完整的 Redmine 站点配置，直接复制粘贴即可，仅需修改 server_name：


user  root;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;


events {
    worker_connections  1024;
}


http {

    # ======== 必须加，缺一不可 ========
    passenger_user_switching off;
    passenger_default_user root;
    # ========================================================
    passenger_root /root/.rbenv/versions/3.3.5/lib/ruby/gems/3.3.0/gems/passenger-6.1.1;
    passenger_ruby /root/.rbenv/shims/ruby;
    passenger_instance_registry_dir /tmp;
    
    include       mime.types;
    default_type  application/octet-stream;

    #log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
    #                  '$status $body_bytes_sent "$http_referer" '
    #                  '"$http_user_agent" "$http_x_forwarded_for"';

    #access_log  logs/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;

  server {
      listen 3000;
      # 这里修改为你的服务器公网IP 或 域名，例如：server_name redmine.yourdomain.com;
      server_name 192.168.6.35;
      # 核心！必须指向redmine的public目录，Passenger的核心规则
      root /opt/redmine/public;
      index index.html index.htm;
  
      # 开启Passenger托管Redmine（核心开关，必须开启）
      passenger_enabled on;
      # 指定Redmine运行环境为生产环境（必须）
      passenger_app_env production;
      # 优化：保持至少1个实例运行，避免首次访问慢
      passenger_min_instances 1;
      # 允许上传大附件（Redmine默认限制，建议设置）
      client_max_body_size 50M;
  
      # 日志配置（可选，单独存放redmine日志，方便排查问题）
      access_log /opt/redmine/log/nginx_access.log;
      error_log /opt/redmine/log/nginx_error.log;
  
      # 静态资源缓存优化（提升访问速度）
      location ~* ^/assets/ {
          expires 1y;
          add_header Cache-Control public;
          add_header ETag "";
      }
  }
}

✅ 保存退出后，必须检查Nginx配置语法是否正确（报错先查这个，99%的配置问题都能检测到）：

/opt/nginx/sbin/nginx -t

✅ 成功标识：nginx: configuration file /opt/nginx/conf/nginx.conf test is successful

步骤 10：权限修复（重中之重，90%的500/403错误根源）

这是部署Redmine的高频坑点！Passenger 模块是通过 Nginx 进程运行的，Nginx 编译安装后默认的运行用户是 nobody，如果 redmine 目录的权限不对，会导致 500内部错误/403权限拒绝/文件写入失败，执行以下命令一次性修复所有权限问题，无脑复制即可：

# 递归赋予读写执行权限
sudo chmod -R 755 /opt/redmine
# 给日志/临时文件/附件目录赋予完整写入权限
sudo chmod -R 775 /opt/redmine/log /opt/redmine/tmp /opt/redmine/files
步骤 11：启动/重启 Nginx，访问 Redmine 系统
  1. 启动/重启 Nginx（Redmine随Nginx自动启动，无需额外启动命令）
# 首次启动
/opt/nginx/sbin/nginx

# 若已启动（修改配置后），执行重启即可
/opt/nginx/sbin/nginx -s reload
  1. 访问 Redmine 系统（浏览器直接访问）

在本地浏览器输入你的服务器IP/域名（即配置文件中的 server_name）：

http://你的服务器IP  或  http://你的域名

✅ 首次访问会稍慢（Passenger 首次加载 Ruby 应用），等待3-5秒后，即可看到 简体中文的Redmine登录页面！

  1. Redmine 默认登录账号（必记）

Redmine 初始化后自带超级管理员账号：

用户名：admin
密码：admin

登录后第一件事：修改默认密码 → 点击右上角 admin → 我的账号 → 修改密码，保障安全。

步骤 12：生产环境必做优化（推荐，提升稳定性和体验）
  1. 设置 Nginx 开机自启（服务器重启后自动运行Redmine）

之前我们配置过的系统服务，直接启用即可：

sudo systemctl enable nginx-passenger
sudo systemctl start nginx-passenger
  1. 配置 Redmine 邮件通知（必备）

Redmine 的邮件通知是核心功能，编辑 /var/www/redmine/config/configuration.yml，复制模板并修改邮箱信息即可，支持QQ邮箱/163邮箱/企业邮箱。

  1. 开启防火墙放行80端口（云服务器必做）
# CentOS
sudo firewall-cmd --permanent --add-port=80/tcp && sudo firewall-cmd --reload
# Ubuntu
sudo ufw allow 80/tcp && sudo ufw reload
  1. 定期备份 Redmine 数据
# 备份数据库（核心）
mysqldump -uredmine -p your_redmine_password redmine > redmine_$(date +%Y%m%d).sql
# 备份redmine文件（附件/配置/插件）
tar -zcvf redmine_files_$(date +%Y%m%d).tar.gz /var/www/redmine/files /var/www/redmine/config
常用运维命令（收藏备用，日常维护足够）

✔️ Nginx + Passenger 相关

# 启动Nginx（Redmine启动）
/opt/nginx/sbin/nginx
# 停止Nginx（Redmine停止）
/opt/nginx/sbin/nginx -s stop
# 重启Nginx（修改配置后必执行）
/opt/nginx/sbin/nginx -s reload
# 检查配置语法
/opt/nginx/sbin/nginx -t
# 查看Passenger运行状态
passenger-status

✔️ Redmine 相关（需进入 /var/www/redmine 执行）

cd /var/www/redmine
# 重启Redmine应用（无需重启Nginx，修改代码/插件后用）
bundle exec passenger-config restart-app .
# 查看Redmine版本
bundle exec rake redmine:info RAILS_ENV=production
# 数据库备份
RAILS_ENV=production bundle exec rake db:backup
✅常见报错 & 解决方案
❌ 报错1：浏览器访问报 500 Internal Server Error（最常见）
  • 原因：90%是权限问题，10%是依赖安装不全/数据库配置错误
  • 解决方案：
    1. 先执行第六步的权限修复命令，重新赋权；
    2. 查看日志定位问题：cat /var/www/redmine/log/production.log 或 cat /opt/nginx/logs/error.log；
    3. 确认数据库配置 config/database.yml 的账号密码正确。
❌ 报错2：403 Forbidden 权限拒绝
  • 原因：Nginx 没有访问 /var/www/redmine/public 目录的权限
  • 解决方案：执行 sudo chown -R nobody:nobody /var/www/redmine + chmod -R 755 /var/www/redmine
❌ 报错3：页面加载正常，但附件上传失败/图片无法预览
  • 原因：files 目录权限不足，或缺少 ImageMagick 依赖
  • 解决方案：
    1. 赋权：chmod -R 775 /var/www/redmine/files
    2. 重新安装ImageMagick：第二步的系统依赖命令再执行一遍
❌ 报错5：访问速度慢，首次打开需要等很久
  • 原因：Passenger 默认是「按需启动」，首次访问才加载Ruby应用
  • 解决方案：在Nginx配置中添加 passenger_min_instances 1，保持至少1个实例运行。

✨ 部署总结

  1. 本次部署是 生产环境最优方案：Nginx+Passenger 托管 Redmine，无需维护任何 Ruby 进程，稳定、高效、配置简单；
  2. 核心规则：Ruby应用在Passenger中的Nginx配置，root必须指向应用的public目录；
  3. 避坑核心：权限问题是所有报错的根源，只要给足 /opt/redmine 目录的权限，90%的问题都能解决；
  4. Redmine 启动逻辑：Nginx启动 → Passenger加载 → Redmine运行，三者是联动的。

至此，你的 Redmine 已经基于 Nginx+Passenger 成功部署并可以投入生产使用了！🎉

avatar
文章
阅读
粉丝