--- layout: doc title: OpooPress Mailet url: /docs/mailet/ render: true --- OpooPress Mailet 是使用 [Apache Mailet API](http://james.apache.org/mailet/api/index.html) 编写的邮件处理程序，结合 Apache James Server，我们可以通过发送电子邮件的方式来发表博客文章。 ## 一、基本用法只需要向指定的 Email 地址发送邮件即可发表博客文章。邮件格式最好采用**纯文本**，但不是强制的。邮件的标题就是文章的标题，邮件的内容就是文章的正文，这就是 OpooPress Mailet 最基本的用法。关于自定义文章文件名、发布时间、标签、分类等高级应用请阅读后续章节。 ## 二、处理流程 1. OpooPress Mailet 监听指定邮件地址的邮箱，发现符合规则新邮件则调用邮件转博客程序进行处理； 2. 邮件转博客 - 生成博客文章源文件（Markdown, Textile 等格式）； - 调用静态博客引擎生成网站； - 调用静态博客引擎发布网站。 3. 将处理过程和结果信息自动回复邮件给发送者。 ## 三、基本需求 - 邮件服务器 (域名，IP等。例如 VPS) - 邮件服务器应用软件 [Apache James Server 2.3.2](http://james.apache.org/download.cgi#Apache_James_2.3.2_is_the_stable_version) - OpooPress Mailet 软件包 ## 四、搭建流程示例环境如下： - Virtual Private Server (VPS) - RAM: 512M - OS: CentOS 6.4 - 域名: opoopress.mail.opoo.org - IP: 1.2.3.4 - Java OpenJDK 1.7.0 - Apache Maven 3.1.0 - Apache James 2.3.2 ### 4.1 安装 OpooPress 博客请[参考该文档](http://www.opoopress.com/zh/docs/installation/)来安装 Java, Apache Maven 并安装和初始化 OpooPress 博客。完成后应该可以正常运行 OpooPress 的各种指令。 ### 4.2 安装配置 Apache James 1. 在域名管理面板中绑定域名 - 设置域名 `opoopress.mail.opoo.org` `A` 记录为 `1.2.3.4` - 设置域名 `opoopress.mail.opoo.org` `MX` 记录为 `1.2.3.4` 2. 下载 [Apache James Server 2.3.2](http://james.apache.org/download.cgi#Apache_James_2.3.2_is_the_stable_version) 软件包，如 `james-binary-2.3.2.tar.gz`。 3. 解压 James 到 `/usr/local/` ``` tar zxvf james-binary-2.3.2.tar.gz mv james-2.3.2 /usr/local/ ``` 4. 启动和停止 James - 运行 `chmod +x /usr/local/james-2.3.2/bin/*.sh` 修改 James 脚本权限 - 运行 `/usr/local/james-2.3.2/bin/run.sh`，第一次运行会生成 `/usr/local/james-2.3.2/apps/james` 目录 - 键入 `Ctrl + C` 停止 James 5. 修改 James 配置文件 `/usr/local/james-2.3.2/apps/james/SAR-INF/config.xml` - 将所有 `localhost` 替换为您的域名，如 `opoopress.mail.opoo.org` - 将所有 `myMailServer` 替换为你的域名，如 `opoopress.mail.opoo.org` - 将所有 `autodetect="true"` 替换为 `autodetect="false"` - 将所有 `autodetectIP="true"` 替换为 `autodetectIP="false"` - 配置 DNS ```xml 8.8.8.8 8.8.4.4 ... ``` - **可选**：如果需要从外部调用 SMTP 发邮件，请注释 `RemoteAddrNotInNetwork=127.0.0.1` 所在的节点，并去掉 `` 段 `` 和 `` 节点的注释。OpooPress Mailet 本身是不需要修改该项配置的。 6. 添加用户。运行 `/usr/local/james-2.3.2/bin/run.sh` 启动 James，`telnet` 到 `4555` 端口进行管理。 ``` JAMES Remote Administration Tool 2.3.2 Please enter your login and password Login id: root Password: root Welcome root. HELP for a list of commands ``` 运行 `adduser ` 添加邮件用户 ``` adduser site1 site1password adduser site2 site2password adduser site3 site3password ``` 添加用户后，可在邮件客户端（如 Foxmail）中进行测试。设置用户 site1, site2, site3 的 POP3 和 SMTP 地址为你的域名（如 opoopress.mail.opoo.org），然后使用第三方邮箱（如 Gmail）分别向这几个邮箱里发送邮件，检查邮件接收情况。也可以使用这几个邮箱互发邮件（需要按第五步配置允许外部调用 SMTP）测试其发送和接收情况。 ### 4.3 安装配置 OpooPress Mailet 1. 安装 OpooPress Mailet 软件包。目前需要从源码打包 OpooPress Mailet 软件包。 ``` git clone https://github.com/opoo/opoopress.git cd opoopress/mailet mvn package mvn dependency:copy-dependencies ``` 运行后，会在 `opoopress/mailet/target` 目录中生成 `opoopress-mailet-.jar` 的软件包，并将依赖的 jar 包复制到 `opoopress/mailet/target/dependency` 目录。将 `opoopress/mailet/target/opoopress-mailet-.jar` 和 `opoopress/mailet/target/dependency` 目录中的所有 Jar 包（junit 除外）复制到 Apache James 目录 `/usr/local/james-2.3.2/apps/james/SAR-INF/lib/` 下，如果 `lib` 不存在，则需要先创建。 ``` mkdir /usr/local/james-2.3.2/apps/james/SAR-INF/lib/ cp target/opoopress-mailet-*.jar /usr/local/james-2.3.2/apps/james/SAR-INF/lib/ rm target/dependency/junit-*.jar cp target/dependency/*.jar /usr/local/james-2.3.2/apps/james/SAR-INF/lib/ ``` 2. 修改 Apache James 配置 `/usr/local/james-2.3.2/apps/james/SAR-INF/config.xml`，在 `` 节点中插入 OpooPress Mailet 配置 ```xml /home/sites/opoopress-site1/site mvn op:deploy /home/sites/opoopress-site2/site mvn op:deploy ``` 每个博客（站点）都由一个 `` 节点来进行配置。其中 - **match 参数**：即 match `=` 后的字符串。邮件接收地址和邮件发送人地址中使用 `|` 分隔，多个地址之间使用 `,` 分隔。只有接收地址和发送地址都匹配时，mailet 才会调用。接收地址都必须是当前 Apache James 服务器中有效的账户。发送地址可以是任意有效的邮件地址，如果使用当前 Apache James 服务器的账号作为发送人地址，则必须开启 James 的 SMTP 认证（参考前面章节）。 - **site**：当前 mailet 要处理的 OpooPress 博客（站点）的主目录。 - **command**: mailet 将博客文章成功保存后，要执行的命令。 - 通常是 `mvn deploy`，会以 **site** 的上级目录作为工作目录（因为 pom.xml 文件位于该目录）。 - 如果一个 pom.xml 下有多个站点，例如多站点 [OpooPress.com](https://github.com/opoo/opoopress.com)，该属性可能是 `mvn deploy -Dsite=zh`，而 site 属性可能是 `/home/sites/opoopress.com/zh`。 - 如果有较为复杂的处理，也可以写成脚本，在这里配置脚本脚本路径。例如发布博客并提交 git 的脚本 `/home/scripts/deploy_my_site.sh` ``` cd /home/sites/opoopress-site1 mvn deploy git add site/source git commit -a -m "Add new post" git push ``` ### 4.4 使用邮件发布博客本章示例讲解的是 OpooPress Mail 的高级应用，文章开头已经讲过基本用法。使用**纯文本**格式向指定的邮件地址（如 site1@opoopress.mail.opoo.org）发送文章内容，示例见下图 ![OpooPress Blogging by Mail Snapshot](http://www.opoo.org/wp-content/uploads/2013/opoopress-blogging-by-mail-snapshots.png) **邮件标题** 邮件的标题会被解析成文章的`标题`和 `name`。 `标题`和 `name` 两个值通过以下规则解析： - 如果邮件标题包含分隔符 `|`，则分隔符前的是`标题`，分隔符后的是 `name`。例如 "世界，你好|hello-world"，"世界，你好|hello world" 或者 "世界，你好|2013-08-13-hello-world.textile" - 如果邮件标题没有分隔符，则文章 `标题` 和 `name` 都等于邮件标题。在确定 `name` 属性后，`name` 属性会被 [SlugHelper](https://github.com/opoo/opoopress/blob/master/core/src/main/java/org/opoo/press/SlugHelper.java) 处理成 `slug` 形式。这个 `slug` 形式的 `name` 决定了将要生成的文章源文件的文件名，也决定了最后生成的文章的 URL（除非在内容里明确指定了 URL）。通过以下一些示例来讲解 `name`、`文章源文件名` 和 `文章 URL` 之间的关系，这里假设当前博客的 `permalink` 格式为 `/article/${'$'}{name}/`，当前日期是`2013年08月13日`： - Name: Hello Mail - 文件名: 2013-08-13-hello-mail.markdown - 文章 URL: /article/hello-mail/ - Name: 2013-08-13-hello-mail - 文件名: 2013-08-13-hello-mail.markdown - 文章 URL: /article/hello-mail/ - Name: 2013-08-13-hello-mail.textile - 文件名: 2013-08-13-hello-mail.textile - 文章 URL: /article/hello-mail/ - Name: hello-mail.textile - 文件名: 2013-08-13-hello-mail.textile - 文章 URL: /article/hello-mail/ **邮件内容** 邮件的内容即文章源文件的内容，其格式遵循 OpooPress 源文件格式： - 可以包含 [YAML front-matter](http://www.opoopress.com/zh/docs/frontmatter/) 的头部，如果不包含，则 OpooPress Mailet 会自动添加头部信息。 - 如果头部不包含 `title` 变量，则使用上一步骤中解析出的标题。如果包含，则忽略从邮件标题解析出的标题。 - 如果头部不包含 `date` 变量，则使用邮件标题中解析中的时间或者当前时间。上面图示的邮件发布后的效果见。 **邮件回复** OpooPress Mailet 运行过程情况会通过邮件回复给发件地址人，邮件的内容是：发生异常时的异常堆栈信息，成功执行命令时的输出，执行过程中的日志信息等，邮件的附件是该文章的源文件。示例如下： ``` File writen: /home/sites/mysite/site/source/article/2013-08-13-this-is-a-post-publish-by-email.markdown Execute command: mvn op:deploy ======================== [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building My OpooPress.com site 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- opoopress-maven-plugin:1.0.1-SNAPSHOT:deploy (default-cli) @ my-opoopress-site --- [INFO] The site directory is : /home/sites/mysite/site [INFO] Skipping install, site already installed. [INFO] Skipping sass compile, css file is up to date. [INFO] File '/home/sites/mysite/site/source/article/2013-08-13-this-is-a-post-publish-by-email.markdown' is newer than 'Tue Aug 13 07:08:08 UTC 2013' [INFO] Source file has been changed after time 'Tue Aug 13 07:08:08 UTC 2013', regenerate site. [INFO] Reading sources ... [INFO] Rendering ... [INFO] Writing files ... [INFO] Writing 2 posts [INFO] Writing 12 pages [INFO] Copying 1 assets directory [INFO] Generate time: 492ms [INFO] Destination [/home/sites/mysite/target/public/site] ... ``` ## 五、注意事项 **安全性** 出于安全性考虑。Apache James、OpooPress Mailet 安装、配置、调试完成后，必须再次修改 Apache James 配置文件 `config.xml`。 * 禁用远程管理服务：`` 节点 `enabled` 改为 `false`。 * 禁用 NNTP 服务：`` 节点 `enabled` 改为 `false`，并将 `` 中的 `threadCount` 改为 `0`。 **服务** 如果要以服务（后台进程）的形式运行 Apache James，请使用以下命令: ``` /usr/local/james-2.3.2/bin/phoenix.sh start ``` 停止 ``` /usr/local/james-2.3.2/bin/phoenix.sh stop ```