Redmine 5.1.4 Git 插件（包括Additionals）安装详细操作

适用环境：Redmine 5.1.4 + Docker + Ruby 3.2 + Rails 6.1
插件版本：Additionals 3.4.0
依赖 Gem：tanuki_emoji ~> 0.10.0

---

0️⃣ 前提条件

1. Redmine 已运行（Docker 容器或裸机均可）
2. Docker 容器内可访问网络（用于 bundle 安装 Gem）
3. 宿主机与容器文件共享或可拷贝插件
4. 基础命令可用：bash、tar、chown、bundle

---

1️⃣ 插件下载与版本选择

1. 从 GitHub 克隆 Additionals 仓库：

git clone https://github.com/alphanodes/additionals.git additionals
cd additionals

1. 切换到与 Redmine 5.1.4 兼容的低版本：

git checkout 3.4.0

1. 打包插件（可选）

tar -czvf additionals-3.4.0.tar.gz additionals/

⚠️ 注意：插件版本必须和 Redmine 主版本兼容，否则迁移会报 [Unknown migration version "7.2"] 错误。

---

2️⃣ 拷贝插件到 Redmine 容器

1. 查看容器 ID

docker ps

1. 拷贝插件目录（优先使用目录而非 tar）

docker cp additionals <container_id>:/usr/src/redmine/plugins/

1. 设置容器内权限

docker exec -it <container_id> bash
cd /usr/src/redmine/plugins
chown -R redmine:redmine additionals

⚠️ 注意：

• 直接拷贝 .tar.gz 文件容易出现路径错误。
• Redmine 容器内必须保证插件目录属于 Redmine 用户。

---

3️⃣ Gem 依赖处理

1. 进入容器 Redmine 根目录

cd /usr/src/redmine

1. 安装插件依赖 Gem

bundle add tanuki_emoji --version "~>0.10.0"
bundle install

1. 处理 Gemfile 重复声明（redmineup、puma）

• 打开 Gemfile（容器内可用 nano 或宿主机修改）
• 删除重复行，只保留一行声明

⚠️ 注意：

• Redmine 5.1.4 对部分 Gem 版本有限制，高版本 Gem 可能导致迁移失败。
• 确认 bundle 源可访问，国内可使用 Ruby China 镜像。

---

4️⃣ 数据库迁移文件兼容性修正

1. 进入插件迁移目录：

cd /usr/src/redmine/plugins/additionals/db/migrate/

1. 修改迁移文件版本

• 例如报错：

ArgumentError: Unknown migration version "7.2"; expected one of "4.2", "5.0", "5.1", "5.2", "6.0", "6.1"

• 修改文件开头：

class RemoveDuplicatedIndexFromRoles < ActiveRecord::Migration[7.2]
# 改为
class RemoveDuplicatedIndexFromRoles < ActiveRecord::Migration[5.1]

⚠️ 注意：

• 所有迁移文件必须与 Rails 6.1 支持的版本匹配。
• 如果插件迁移中还有 disable_ddl_transaction!，确认语法兼容。

---

5️⃣ 执行插件迁移

1. 执行数据库迁移

bundle exec rake redmine:plugins:migrate RAILS_ENV=production

1. 迁移过程中可能出现警告：

WARN -- : Creating scope :visible. Overwriting existing method AgileQuery.visible.

• 这种警告可以忽略，不影响插件功能。

⚠️ 注意：

• 如果迁移报错，请检查迁移文件版本、依赖 Gem 是否安装。
• 遇到重复列或索引，可手动修改数据库或跳过对应迁移。

---

6️⃣ 重启 Redmine 容器

docker restart <container_id>

⚠️ 注意：

• Docker 容器内修改插件或 Gem 后必须重启 Redmine 才能生效。
• 检查 Redmine 日志确保无报错。

---

7️⃣ 常见坑与解决方案总结

类别	坑	解决方法
版本兼容	插件版本高，迁移版本 7.2	降级迁移版本 [5.1]
Gem	缺少 tanuki_emoji	bundle add tanuki_emoji --version "~>0.10.0"
Gem	Gemfile 重复	删除重复声明
文件	docker cp 找不到文件	拷贝文件夹而非 tar
权限	容器内权限不足	chown -R redmine:redmine plugins/additionals
编辑器	vim 不存在	安装 nano 或宿主机编辑后复制
迁移	数据库已存在列	手动 skip 或修改 migration
Docker	端口冲突	调整映射端口
日志	Scope 警告	可忽略，不影响功能

---

8️⃣ 最佳实践

1. 先备份数据库和插件目录
2. 优先使用低版本插件
3. 保证 bundle 环境和 Gemfile 清洁
4. 容器内使用 Redmine 官方用户操作插件
5. 迁移前修改 migration 版本，确保 Rails 兼容
6. 安装插件依赖 Gem 并锁定版本
7. 迁移完成后重启 Redmine 容器
8. 检查插件在 Redmine 页面是否启用