Redmine通过邮件提交问题(issue)的配置

转载：http://redmine.ossxp.com/redmine/documents/4#从邮件服务器转发邮件

 

Redmine通过邮件提交问题(issue)的配置

用户文档
2010-03-24

从Redmien-0.8.0 开始, 通过配置, 你可以以发送邮件的方式创建或者评论问题(issue).

设置¶

你可以通过以下几种方式配置Redmine接收邮件的功能:

• 从邮件服务器转发邮件
  • 优点：与远程邮件服务器协作，邮件处理即时，快速（无环境重载）
  • 缺点：需要一些邮件传输代理(MTA)的配置（如Postfix，Sendmail...）
• 从IMAP或者POP3服务器读取邮件
  • 优点: 易于安装, 不需要配置邮件传输代理(MTA), 与远程邮件服务器协作
  • 缺点: 邮件处理不即时(需要添加一个定期读取邮件的 cron job)
• 从标准输入读取邮件
  • 优点: 用于测试的最佳选项
  • 缺点: 慢(每次读取邮件时都要重新载入环境), 需要配置邮件传输代理(MTA)

从邮件服务器转发邮件¶

用一个独立的脚本转发邮件服务器发来的邮件.这个脚本从标准输入读取原始邮件并通过HTTP请求转发给Redmine. 该脚本在redmine目录下: extra/mail_handler/rdm-mailhandler.rb
使用这项功能之前, 你需要开启接收邮件的API:
开启操作: "管理"->"配置"->"接收邮件", 选中开启 接收邮件服务 的复选框,并点击链接"生成一个key",产生一个密钥.
复制rdm-mailhandler.rb到你的邮件服务器, 确保该脚本有执行的权限并配置你的邮件传输代理(MTA).

用法:

rdm-mailhandler [options] --url=<Redmine URL> --key=<API key>
必须选项:
-u, --url                      Redemine服务的URL
-k, --key                      Redmine API key

常用可选选项:
-h, --help                     显示帮助信息
-v, --verbose                  显示额外的信息
-V, --version                   显示版本信息

问题属性可控的选项:
-p, --project=PROJECT 项目的标识符
-t, --tracker=TRACKER 跟踪标签的类型
--category=CATEGORY 类别的名称
--priority=PRIORITY 优先级的名称
-o, --allow-override=ATTRS 允许在邮件内容里覆盖先前已指定的属性，多个属性之间用逗号分开

更多@--allow-override@ 选项，参见 问题issue属性
示例:

# 没有指定项目，那么在邮件内容里必须包含“Project”关键字，否则Redmine将不处理该邮件
rdm-mailhandler --url http://redmine.domain.foo --key secret
# 设置默认的项目和跟踪标签类型，同时可以在邮件内容里覆盖tracker和priority选项
rdm-mailhandler --url https://domain.foo/redmine --key secret 
               --project foo \\
               --tracker bug \\
               --allow-override tracker,priority

下面是一个Postfix的例子:

foo: "|/path/to/rdm-mailhandler.rb --url http://redmine.domain --key secret --project foo" 

这行指令应该在一个别名文件中，通常在/etc/aliases中。如果找不到，可以使用命令 postconf alias_maps 找到。更新aliases文件后，记得运行newaliases提示Postfix有新的实体添加。

如果你的域名是一个虚拟的的邮箱映射（即用 /etc/postfix/virtual_mailbox_maps 去映射 user@example.com /path/example.com/user)，你应该做一下操作：

• 在/etc/virtual中创建映射：例如 foo@example.org foo
• 修改 /etc/postfix/main.cf ,指定一个传输文件：transport_maps = hash:/etc/postfix/transport
• 在指定的传输文件中添加一行： foo@example.org local:

从IMAP服务器读取邮件:¶

redmine提供了一个rake任务(redmine:email:receive_imap)负责从IMAP服务器读取邮件. 当通过cron 运行该rake命令时你需要使用选项 -f /path/to/redmine/appdir/Rakefile, 因为不这样的话会出现找不到rakefile的异常.

下面是一个定期每30分钟读取一次邮件的cron文件:

*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx 

如果你的设置正常工作，但经常收到cron daemon发送的邮件，你可以在rake命令后添加 --silent选项禁止执行命令的输出信息。下面是
禁止每次执行cron命令时发送邮件的示例

*/30 * * * * redmineuser rake -f /path/to/redmine/appdir/Rakefile --silent redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=redmine@somenet.foo password=xxx

在cron文件中,这个命令必须位于一行上. 另请参阅下面的其他例子, 只显示没有-f 选项的rake命令而且没有cron部分.

如果用Windows作为服务器, pycron 可以用于调度读取邮件的任务.

同时需要你修改防火墙设置, 打开同通过TCP链接IMAP的143端口.

可用的IMAP选项:

host=HOST           IMAP服务主机(_默认值: 127.0.0.1_)
port=PORT                IMAP服务端口(_默认值: 143_)
ssl=SSL                  是否使用SSL？(默认值: false)
username=USERNAME       IMAP 账号
password=PASSWORD       IMAP 密码
folder=FOLDER             将要读取的IMAP文件夹(_默认值: INBOX_)
move_on_success=MAILBOX  将已成功读取的邮件移动到MAILBOX中， 而不是删除掉
move_on_failure=MAILBOX   将Redmine忽略的邮件移动到MAILBOX中

问题(issue)属性可控的选项:

project=PROJECT          项目标识符
tracker=TRACKER          跟踪标签类型
category=CATEGORY       问题类别名称
priority=PRIORITY          优先级名称
allow_override=ATTRS      允许在邮件内容里覆盖先前已指定的属性，多个属性之间用逗号隔开

更多@--allow-override@ 选项，参见 问题issue属性
rake命令的一个例子:

# 没有指定项目， 这时邮件内容里必须包含“Project”关键字
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx
# 指定默认的项目和跟踪标签类型， 同时允许在邮件里覆盖tracker和priority属性的值
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx ssl=1 \\
project=foo \\
tracker=bug \\
allow_override=tracker,priority
# 将成功处理的邮件转移到“read”mailbox中，失败的则转移到“failed”mailbox中
rake redmine:email:receive_imap RAILS_ENV="production" \\
host=imap.foo.bar username=redmine@somenet.foo password=xxx \\
move_on_success=read move_on_failure=failed

忽略的邮件（包括未知用户、未知项目以及来自redmine禁用帐户的邮件）被标记为'已读'，而不是从IMAP服务器中删除。

选项 allow_override 不仅仅覆盖rake的默认值, 而且可以覆盖邮件里的所有属性. 例如，你要覆盖tracker, 你可以添加参数: allow_override=tracker

从POP3服务器读取邮件¶

仅在trunk和1.0以后的版本可用

redmine提供的rake任务(redmine:email:receive_pop3)可以用于从POP3读取邮件

POP3可用的选项:

host=HOST                POP3服务主机(_默认值: 127.0.0.1_)
port=PORT                POP3服务端口(_默认值: 110_)
username=USERNAME       POP3账号
password=PASSWORD       POP3密码
apop=1                   使用APOP认证(_默认值: false_)
delete_unprocessed=1     从服务器上删除不能成功处理的消息(_默认情况是继续保存在服务器上_)

关于问题属性的可控选项可以参考上面IMAP章节

从标准输入读取邮件¶

redmine提供的rake任务(redmine:email:receive)用于从标准输入读取单个的原始邮件

问题属性可控的选项:

project=PROJECT          项目标识符
tracker=TRACKER         跟踪标签类型
category=CATEGORY       问题类别名称
priority=PRIORITY          优先级名称
allow_override=ATTRS     允许在邮件内容里覆盖先前已指定的属性，多个属性之间用逗号分开

更多@--allow-override@ 选项，参见 问题issue属性
示例:

# 没有指定项目，这时邮件里必须包含“Project”关键
rake redmine:email:read RAILS_ENV="production" < raw_email
# 指定默认的项目和跟踪标签类型，并且允许在邮件里覆盖tracker和priority选项
rake redmine:email:read RAILS_ENV="production" \\
project=foo \\
tracker=bug \\
allow_override=tracker,priority < raw_email

选项 allow_override 不仅仅覆盖rake的默认值, 而且可以覆盖邮件里的所有属性. 例如，你要覆盖tracker, 你可以添加参数: allow_override=tracker

开启匿名用户通过邮件提交问题¶

为了开启该选项，需要添加额外参数

unknown_user=ACTION 当收到未知用户邮件时，应该采用哪种ACTION。以下是ACTION可用的值：
    ignore: 邮件将被忽略（默认值）
    accept: 作为匿名用户接收
    create: 自动为该用户创建一个账号

    no_permission_check=1 当收到邮件时禁用权限检查功能

工作原理:¶

收到邮件后, Redmine从发件人地址中查找对应的账号. 未知用户和已锁定的用户将被忽略.

如果邮件主题包含像这样的内容" Re:[xxxxxx #123]", 那么该邮件将被作为问题(issue)#123的回复处理.
否则将会以邮件主题为问题的标题，新建一个问题(issue)

目标项目:¶

目标项目可以通过接收邮件里的project选项指定. project应该用项目的标识符，而不是项目的名称来指定.

如果不使用该选项, 你需要在邮件内容中指定问题关联的项目. 你可以在邮件里添加这样一行: "project:foo".

例子(邮件内容):

Project: foo
在这里可以写一些关于问题的描述信息

你可以给项目选项指定一个默认的项目并允许并允许用户通过 allow_override 选项覆盖默认的项目.

例子:

# 指定默认项目，并允许用户在邮件内容里覆盖project属性
rake redmine:email:receive_imap [...] project=foo allow_override=project

当然, 用户的权限也会别检查, 那些没有创建问题(issue)的用户发送的邮件将被忽略.

同时必须确保目标项目没有使用尚未指定默认值的用户自定义问题(issue)字段, 否则创建问题(issue)将会失败.

问题(issue)属性¶

根据你使用的接收邮件选项(参考 allow_override 选项), 用户可以在提交问题(issue)时覆盖一些属性.

可以在邮件里用以下关键字实现:Tracker, Category, Priority, Status.

例子:

这是一个新问题， 并将覆盖一些属性
[...]
Project: foo
Tracker: Bug
Priority: Urgent
Status: Resolved

跟踪者¶

如果发送邮件的用户有"添加问题(issue)跟踪者"的权限, 邮件中To或者Cc字段里的用户将作为新建问题(issue)的跟踪者

邮件格式以及附件¶

Redmine用邮件的纯文本部分填充问题(issue)的描述. 因此当收到一个仅有HTML的邮件, 那些HTML标签将被删除.

邮件的附件将会自动附加给问题(issue), 除非超过了应用程序设置的附件最大值.

演示¶

下面介绍一下我的具体配置步骤， 以从IMAP服务器读取邮件为例

从IMAP服务器读取邮件的演示¶

添加一个Redmine从IMAP服务器读取邮件的corn任务

wangsheng@pc01:/etc/cron.d$ cat receive_imap
# m h  dom mon dow  user  command
*/10 *  *   *   *    root rake -f /opt/redmine/web/Rakefile redmine:email:receive_imap RAILS_ENV="production" host=imap.foo.bar username=xxx@foo.bar password=xxxxxx allow_override=tracker

说明：

• 这个任务会每隔10分钟执行一下那个rake命令
• usernname最好跟"管理"->"配置"->"邮件通知"界面里的 邮件发件人地址 相同, 否则当你直接回复邮件更改问题时可能会出现收件人地址不可达的异常(如果你在该界面配置了一个不存在的邮件账号). 最理想的做法是给Redmine创建一个IMAP账号, 写在这里.

好了， 下面发送一个测试邮件：
收件人:

rake里的username值

邮件标题：

# 这将是新建问题的标题
这是通过邮件提交的问题

邮件内容：

# 由于在rake命令里没有指定默认项目，所以这里必须指定项目
Project: 项目标识符
Tracker: 支持
下面可以写一些关于问题的描述

说明:
该邮件将会创建一个"支持"类型的问题(issue)

如果10分钟内，你访问Redmine， 点击问题选项卡， 看到了这个问题， 那么证明已经成功配置。

文件