使用 Isso 可以为静态网页添加自有评论系统,前提是需要有一台服务器。有兴趣的话,可以先看我的使用体验七、使用体验

一、安装

首先安装 Isso 所需的软件(可以先查看系统是否默认已安装):

  • Python 2.6, 2.7 或 3.3+(+devel 头文件)
  • SQLite 3.3.8 或更高版本
  • 一个有效的 C 编译器
$ # Debian & Ubuntu
$ sudo apt-get install python-dev sqlite3 build-essential

$ # Fedora & CentOS
$ sudo yum install python-devel sqlite
$ sudo yum groupinstall "Development Tools"

安装 pip:

$ # Debian & Ubuntu
$ sudo apt-get install python-pip

$ # Fedora & CentOS
$ sudo yum -y install python-setuptools && sudo easy_install pip

安装完 pip 后,使用 pip 安装 Isso:

$ sudo pip install isso

如果需要升级 Isso 的话:

$ sudo pip install --upgrade isso

二、服务器配置

新建一个数据库存放目录:

$ sudo mkdir /var/lib/isso

新建一个配置文件:

$ sudo vi /etc/isso.conf

编辑内容如下(部分参数未使用,见下面的参数解析,可根据需求进行修改):

[general]
dbpath = /var/lib/isso/comments.db
host = https://www.practicemp.com/
max-age = 0
notify = smtp
[moderation]
enabled = false
[server]
listen = http://localhost:8080
[smtp]
username = 账户名
password = 密码
host = smtp 服务器地址
port = 465
security = ssl
to = 收件地址
from = 发件地址(通常是账户名)
timeout = 10
[guard]
enabled = true
ratelimit = 2
direct-reply = 3
require-author = true
require-email = true

参数解析:

[general] 部分:

  • dbpath: 数据库位置,检查权限,如果不存在则自动创建。Isso 使用的是 SQLite 作为数据库,所以需要提前装好。
  • host: 你要使用 Isso 评论的网站地址。不是 Isso 的!
  • max-age: 评论者可以删除或修改自己评论的时间。15m 就代表在 15 分钟内可以删除和修改自己的评论。
  • notify: 当有新评论时后台如何通知,可选值有 stdoutsmtp,但 stdout 可能在最近的版本中已不可用。所以推荐使用 smtp

[moderation] 部分:

  • enable: 是否开启评论审核。在审核通过之前,其他用户看不到审核中的评论。
  • purge-after: 在多长时间后删除还在审核中的评论,如 30 天 - 30d

[server] 部分:

  • listen: Isso 服务监听的 TCP/IP 地址或者套接字文件(例如 unix:///tmp/isso.sock)。
    如果 gevent 可用,它将自动监听 http://,目前 gevent 无法处理来自套接字的请求。
    不适用于 uWSGI
    注:关于这部分可以通过后面的部署章节进行了解。

[smtp] 部分:

  • username: 用户名。如果是本地 MTA 的话可选。
  • password: 密码,纯文本,为通知创建的专用账户。如果是本地 MTA 的话可选。
  • host: SMTP 服务器地址。
  • port: SMTP 服务器端口号。
  • security: 使用安全的方式与 SMTP 服务器连接。可选值:nonestarttlsssl。注意,Python 2.7 和 Python 3.3 没有简单的方法来进行证书验证,所以与 SMTP 服务器的链接会受到中间人攻击。因此,你绝对应该创建一个 Isso 的专用 SMTP 账户。
  • to: 收件人地址,例如你的邮箱地址。
  • from: 发件人地址。例如: 新评论 <isso@example.tld>,这里面的 新评论 是定义发件人名,不是邮件主题。
  • timeout: 连接 SMTP 服务器的超时限制。单位秒。

[guard] 部分:

  • enabled: 是否启用 guard,推荐在生产环境中启用。
  • ratelimit: 每个评论者每分钟最多评论几次。
  • direct-reply: 直接评论的次数上限。例如,如果设定为 3,则一个评论者最多直接评论 2 条,第 3 条评论将会被服务器拒绝。回复其他人的评论不限。
  • reply-to-self: 当 max-age 启用且评论者还可以编辑自己的评论时,是否允许回复自己的评论。需要配合后面客户端中的配置。
  • require-author: 是否强制评论者填写名称。Isso 不会验证其有效性。需要配合后面客户端中的配置。
  • require-email: 是否强制评论者填写邮箱。Isso 不会验证其有效性。需要配合后面客户端中的配置。

[markup] 部分: Markdown 功能由Misaka插件提供。

  • option: 指定的 Misaka Markdown扩展插件。以 EXT_ 开头的标记都能使用,用逗号分隔。
  • allowed-elements: 附加的 HTML 标签,用逗号分隔。默认情况下,只有 ablockquotebrcodedelemh1h2h3h4h5h6hrinsliolpprestrongtabletbodytdththeadul 可用。
  • allowed-attributes: 附加的 HTML 标签属性,用逗号分隔。默认情况下,只有alignhref可用。

要想允许在评论中出现图片,你仅需要在 [markup] 部分添加 allowed-elements = imgallowed-attributes = src 两个参数。

[hash] 部分: 使用哈希算法隐藏评论者的邮箱(实际测试不起作用)

  • salt: 加盐是为了对抗彩虹表。自 Isso 发布以来,一直使用默认值,为跨安装的相同地址生成相同的标识符。
  • [algorithm]: 使用的哈希算法 - 无论是来自 Python 的 hashlib 还是 PBKDF2
    PBKDF2 的实际标识符是 pbkdf2:1000:6:sha1,这意味着 1000 次迭代,生成 6 个字节,SHA1 作为用于密钥强化的伪随机族。参数必须以这样的顺序排列,但可以简化,例如仅覆盖迭代次数:pbkdf2:4096

三、配置 Nginx

与你的网站相同的域上运行 Isso,从而避免源自 CORS 的问题。并且,隐私保护浏览器插件(如请求政策)也不会阻止评论。

server {
    listen       [::]:80;
    listen       [::]:443 ssl;
    server_name  example.tld;
    root         /var/www/example.tld;

    location /isso {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Script-Name /isso;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:8080;
    }
}

配置完成后重启 Nginx:

$ sudo nginx -t
$ sudo nginx -s reload

按照上面的配置过后,Isso 服务器端已经可以运行了,:

$ sudo isso -c /etc/isso.conf run

要停止的话按 ctrl + C。这时还无法看到效果,还需要配置一下客户端。

四、客户端配置

4.1 添加评论框

你可以通过定制的 data属性来配置客户端,最好是嵌入到 script 标签中。下面是一个简单的例子:

<!--在需要添加评论框的地方插入下面的 section 标签-->
<section id="isso-thread"></section>
<!--然后引入 embed.min.js 插件-->
<script data-isso="/isso/"
        data-isso-require-author="true"
        data-isso-require-email="true"
        data-isso-max-comments-top="20"
        data-isso-max-comments-nested="10"
        data-isso-reveal-on-click="20"
        src="/isso/js/embed.min.js"></script>

另外,你可以使用如下的标签来覆盖 Isso 的自动标题检测:

<section id="isso-thread" data-title="Foo!"></section>

参数解析:

  • data-isso: Isso 通常会自动检测 REST API,但是当你在其它位置提供 JS 脚本时,可能会失败。使用 data-isso 来覆盖 API 位置:
<script data-isso="/isso" src="/path/to/embed.min.js"></script>
  • data-isso-css: 设置为 false 可防止 Isso 自动附加样式表。默认为 true
<script src="..." data-isso-css="false"></script>
  • data-isso-lang: 覆盖网页的首选语言。Isso 已经被翻译为超过 12 种语言。可以用 ISO 639-1 代码(双字母)来配置。你可以在 GitHub 找到所有支持的语言列表。注意:中文为 zh,设为 zh_CN 无效。如果你在 <html> 标签中设置了 lang=zh_CN 属性,Isso 会自动检测到,这项就可以省略。
  • data-isso-reply-to-self: 默认为 false。当服务器配置文件中设置了 reply-to-self = true 时,此项也要设置为 true
  • data-isso-require-author: 默认为 false。当服务器配置文件中设置了 require-author = true 时,此项也要设置为 true
  • data-isso-require-email: 默认为 false。当服务器配置文件中设置了 require-email = true 时,此项也要设置为 true
  • data-isso-max-comments-topdata-isso-max-comments-nested: 初始展示的顶层评论数和嵌套评论数。如果有评论未展示出来,将会显示一个 X Hidden 链接。
    设置为 inf 显示全部评论,或者设置为 0 隐藏全部评论。
  • data-isso-reveal-on-click: 当点击 X Hidden 链接时显示的评论数量。
  • data-isso-avatar: 启动或禁用头像,默认为 true
  • data-isso-avatar-bg: 设置头像背景色。任何有效的 CSS 颜色都可以。
  • data-isso-avatar-fg: 设置头像前景色。最多有 8 种颜色。默认颜色方案基于此调色板。多种颜色必须用空格分隔。如果使用少于八种颜色并且不是 2 的倍数,否则颜色分布不均匀。
  • data-isso-vote: 启用或禁用投票功能,默认为 true
  • data-isso-vote-levels: 定义评论投票区间,用来决定评论的外观。应提供一个逗号分隔的值(如 0,5,10,25,100),或者 JSON 数组(如 [-5,5,15])。
    例如,如果写入值 -5,5,会将评论分为 3 个等级:

    • isso-vote-level-0 是分数低于 -5 的。
    • isso-vote-level-1 是分数在 -54 之间的。
    • isso-vote-level-2 是分数等于或高于 5 的。

    这些等级可以被用来定义评论的外观(例如给受欢迎的评论加一个星标记)。

4.2 添加评论计数

在需要显示计数的位置插入下面一条 a 标签:

<a href="/my-uri.html#isso-thread">条评论</a>

/my-uri.html 替换为你要计数的页面的 URI。

然后引入计数插件:

在上面添加评论框时引入的 embed.min.js 中已经包含了计数插件功能。而在首页、归档等不许要评论框的页面就只需要引入一个独立的计数插件 count.min.js

<script src="/isso/js/count.min.js"></script>

也就是说一个页面中要进行评论计数,要么引入 embed.min.js,要么引入 count.min.js,二选一即可。

五、部署

在前面启动 Isso 时,使用的是 Isso 内置的 Web 服务器,这对初始设置或低流量的网站很有用,但仅支持每秒最多 20 个请求。可以使用 gevnet 来提高内置服务器的性能。gevent 是一个基于协程Python 网络库。减少了对 IO 操作时的等待时间。而使用 gevent 又需要 libevent 的支持。总之,使用 gevent 可以提高 Isso 内置 web 服务器的性能。

先用 yum 安装 libevent:

$ sudo yum install libevent

然后用 pip 安装 gevent:

$ sudo pip install gevent

安装完 gevent,Isso 的启动命令并不需要改变。

接下来通过 systemd 将 Isso 设置为开机自启:

新建一个 Isso 服务的配置文件:

$ sudo vi /usr/lib/systemd/system/isso.service

编辑内容如下:

[Unit]
Description=Isso Server
After=network.target

[Service]
Type=simple
ExecStart=/bin/isso -c /etc/isso.conf run
Restart=on-failure

[Install]
WantedBy=multi-user.target

然后就可以使用 systemctl 命令来管理 Isso 服务了(如果前面已经启动了 Isso,先关闭):

$ # 启动 Isso 服务
$ sudo systemctl start isso.service
$ # 关闭 Isso 服务
$ sudo systemctl stop isso.service
$ # 将 Isso 服务设为开机自启
$ sudo systemctl enable isso.service

六、备份评论数据库

其实就是备份 var/lib/isso/comments.db 这个文件,由于该数据库文件内容未经加密(即便显式配置了 [hash] 部分),所以不要公开存储。可以使用 git 命令上传到自己的私有仓库,或者使用 Rsync 工具将该文件同步到本地或另一个服务器。

同步服务器评论数据库到本地:

$ rsync --delete -vaz --rsync-path="sudo rsync" -e "ssh -p 端口号" 用户名@服务器IP:/var/lib/isso/ /path/to/store

同步本地评论数据库到服务器:

$ rsync --delete -vaz --rsync-path="sudo rsync" -e "ssh -p 端口号" /path/to/store/ 用户名@服务器IP:/var/lib/isso

七、使用体验

Isso 的 Github 页面可以看到,最新的版本是 2016 年 9 月份发布的 0.10.6,虽然项目还在更新,但已经有 2 年没有发布新版本了。如果想要体验的到最新的功能,必须从 Github 下载源码编译安装。不过,在这个最近的 Issue 里面原作者已将 PyPi 的版本发布和管理权限交给了另外 2 个贡献者,相信过不了多久,就会看到新的 pip 包了。下面的体验只针对 0.10.6:

  • 如果一个页面没有评论,当加载 Isso 时,可以在浏览器控制台页面发现一个 404 错误。这是正常现象,意味着该页面还没有评论。
  • 目前无法对评论排序,最早的评论在最上面。
  • 只能通过邮件来审核评论,或者通过直接修改 SQLite 数据库,没有专用的管理页面。开启评论审核,邮件通知中会有一个审核通过的链接和一个删除评论的链接。如果关闭了评论审核,邮件通知只会有一个删除评论的链接。
  • 目前的版本,在评论时如果遇到次数、频率限制或格式不符时,Isso 没有在页面进行提示,只能在浏览器控制台看到相关输出。
  • 投票功能未完成。
  • 评论只有二级。

八、修改 CSS 及 JS 插件

页面引入 embed.min.js 后,会在页面的 <head></head> 标签中最下面创建一个 <style type="text/css">...</style> 标签,里面就是评论框的样式。评论框的样式是在 embed.min.js中最后面的几个 define 中定义的。如果你熟悉js,可以通过修改修改其源码生成新的 embed.min.js 来实现自己想要的样式和功能,或者通过官网上提供的 api文档 自行编写 JS 客户端。

在服务器上通过下面的命令找到 embed.min.js 的位置:

$ sudo find / -name embed.min.js
(完)