本地搭建并使用 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 可能运行缓慢。

系统架构概述

以下是 Redmine 的基本架构图：

这个图展示了 Redmine 的核心：Rails 应用处理逻辑，数据库存储数据。

安装步骤

我们分步进行安装和配置。以下流程图概述整个过程：

步骤 1: 更新系统和安装依赖

1. 打开终端，运行：

   sudo apt update
   sudo apt upgrade -y
   

2. 安装基本依赖：

   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
   

2. 安装 Ruby（例如 3.0.0，检查 Redmine 兼容版本）：

   rbenv install 3.0.0
   rbenv global 3.0.0
   

3. 安装 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  # 安全配置
   

2. 创建数据库和用户：

   sudo mysql -u root -p
   

   在 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;
   

数据库设置序列图：

步骤 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
   

2. 配置数据库：

   • 复制模板：cp config/database.yml.example config/database.yml
   • 编辑 nano config/database.yml，在 production 部分设置：

     production:adapter: mysql2database: redminehost: localhostusername: redminepassword: "your_password"encoding: utf8mb4
     

3. 安装 gem 依赖：

   bundle config set --local without 'development test'
   bundle install
   

4. 生成密钥并迁移数据库：

   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
   

2. 在浏览器访问 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。

使用流程图：

安全和优化

• 生产服务器：安装 Nginx 和 Passenger：

  sudo apt install -y nginx
  gem install passenger
  passenger-install-nginx-module
  

  配置 Nginx 指向 Redmine。

• 备份：定期备份数据库（mysqldump）和文件（/opt/redmine/files）。

• 安全：启用 HTTPS（Let’s Encrypt），使用强密码，限制访问。

• 更新：下载新版 Redmine，运行迁移。

• Docker 替代：docker run -d -p 3000:3000 redmine（简单但自定义少）。

常见问题和故障排除

• Gem 安装失败：检查 Ruby 版本，确保 bundle install 无缺失依赖。
• 数据库连接错误：验证 database.yml 和 MySQL 用户/密码。
• 端口占用：用 sudo netstat -tuln 检查 3000。
• 性能慢：增加 RAM 或使用 PostgreSQL。
• 邮件配置：编辑 config/configuration.yml，设置 SMTP。
• 日志：查看 log/production.log。

如果问题，参考 redmine.org/wiki 或论坛。

结语

恭喜！你现在有了一个本地 Redmine 实例！它可以用于项目管理、团队协作等。探索插件市场添加功能，如 Agile 或主题。本教程创建基于 Redmine 5.1.x。