中文 | ENGLISH

OpooPress

基于 Java 的静态博客生成器

OpooPress Mailet

OpooPress Mailet 是使用 Apache Mailet API 编写的邮件处理程序，结合 Apache James Server，我们可以通过发送电子邮件的方式来发表博客文章。

一、基本用法

只需要向指定的 Email 地址发送邮件即可发表博客文章。邮件格式最好采用纯文本，但不是强制的。

邮件的标题就是文章的标题，邮件的内容就是文章的正文，这就是 OpooPress Mailet 最基本的用法。关于自定义文章文件名、发布时间、标签、分类等高级应用请阅读后续章节。

二、处理流程

  1. OpooPress Mailet 监听指定邮件地址的邮箱，发现符合规则新邮件则调用邮件转博客程序进行处理；
  2. 邮件转博客
    • 生成博客文章源文件（Markdown, Textile 等格式）；
    • 调用静态博客引擎生成网站；
    • 调用静态博客引擎发布网站。
  3. 将处理过程和结果信息自动回复邮件给发送者。

三、基本需求

  • 邮件服务器 (域名，IP等。例如 VPS)
  • 邮件服务器应用软件 Apache James Server 2.3.2
  • 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 博客

请参考该文档来安装 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 软件包，如 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
      <dnsserver>
<servers>
<server>8.8.8.8</server>
<server>8.8.4.4</server>
</servers>
...
</dnsserver>
    • 可选：如果需要从外部调用 SMTP 发邮件，请注释 RemoteAddrNotInNetwork=127.0.0.1 所在的节点，并去掉 <smtpserver/> 段 <authRequired> 和 <verifyIdentity> 节点的注释。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 <username> <password> 添加邮件用户
    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-<VERSION>.jar 的软件包，并将依赖的 jar 包复制到 opoopress/mailet/target/dependency 目录。

    将 opoopress/mailet/target/opoopress-mailet-<VERSION>.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，在 <spoolmanager><processor name="root"> 节点中插入 OpooPress Mailet 配置

    <mailet match="RecipientIsAndSenderIs=site1@opoopress.mail.opoo.org|writer@opoopress.mail.opoo.org,yourname@gmail.com" class="OpooPressMailet">
    <site>/home/sites/opoopress-site1/site</site>
    <command>mvn op:deploy</command>
</mailet>
<mailet match="RecipientIsAndSenderIs=site2@opoopress.mail.opoo.org|writer@opoopress.mail.opoo.org,yourname@gmail.com" class="OpooPressMailet">
    <site>/home/sites/opoopress-site2/site</site>
    <command>mvn op:deploy</command>
</mailet>

    每个博客（站点）都由一个 <mailet/> 节点来进行配置。 其中

    • match 参数：即 match = 后的字符串。邮件接收地址和邮件发送人地址中使用 | 分隔，多个地址之间使用 , 分隔。只有接收地址和发送地址都匹配时，mailet 才会调用。接收地址都必须是当前 Apache James 服务器中有效的账户。发送地址可以是任意有效的邮件地址，如果使用当前 Apache James 服务器的账号作为发送人地址，则必须开启 James 的 SMTP 认证（参考前面章节）。
    • site：当前 mailet 要处理的 OpooPress 博客（站点）的主目录。
    • command: mailet 将博客文章成功保存后，要执行的命令。
      • 通常是 mvn deploy，会以 site 的上级目录作为工作目录（因为 pom.xml 文件位于该目录）。
      • 如果一个 pom.xml 下有多个站点，例如多站点 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

邮件标题

邮件的标题会被解析成文章的标题和 name。

标题和 name 两个值通过以下规则解析：

  • 如果邮件标题包含分隔符 |，则分隔符前的是标题，分隔符后的是 name。 例如 “世界，你好|hello-world”，“世界，你好|hello world” 或者 “世界，你好|2013-08-13-hello-world.textile”
  • 如果邮件标题没有分隔符，则文章 标题 和 name 都等于 邮件标题。

在确定 name 属性后，name 属性会被 SlugHelper 处理成 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 的头部，如果不包含，则 OpooPress Mailet 会自动添加头部信息。
  • 如果头部不包含 title 变量，则使用上一步骤中解析出的标题。如果包含，则忽略从邮件标题解析出的标题。
  • 如果头部不包含 date 变量，则使用邮件标题中解析中的时间或者当前时间。

上面图示的邮件发布后的效果见 http://demo.opoo.org/demo/。

邮件回复

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。

  • 禁用远程管理服务：<remotemanager/> 节点 enabled 改为 false。
  • 禁用 NNTP 服务：<nntpserver/> 节点 enabled 改为 false，并将 <nntp-repository/> 中的 threadCount 改为 0。

服务 如果要以服务（后台进程）的形式运行 Apache James，请使用以下命令:

/usr/local/james-2.3.2/bin/phoenix.sh start

停止

/usr/local/james-2.3.2/bin/phoenix.sh stop

评论