一、概述

GitHub：https://github.com/posativ/isso

Pypi：https://pypi.org/project/isso

英文文档：https://posativ.org/isso/

Isso是一个使用Python和JavaScript编写的轻量级的开源评论系统， 它旨在成为Disqus的替代产品。

这是一个自建评论服务的项目，所以使用它，您需要有服务器才行。值得一提的是，本站已编写完成开放Isso服务的功能，允许用户直接申请一个站点，不需要额外的服务器。

PS：申请入口是【 Isso评论系统开放服务 】

Isso目前版本是0.12.3，其功能大致如下：

  • 支持Python2.7及3.4+

  • 匿名评论，允许限定昵称、邮箱、网站，且支持使用Markdown撰写评论

  • 使用SQLite存储，无需安装额外服务，系统基本内置支持

  • 支持导入Disqus & WordPress评论

  • 高度可配置的JS客户端

  • 支持评论邮件提醒、审核，回复评论时邮件通知作者

  • 支持gravatar头像

  • 支持在admin界面管理评论

Isso中文文档

GitHub：https://github.com/staugur/isso-cn

Pypi：https://pypi.org/project/isso-cn

中文文档：https://isso-cn.rtfd.vip

Isso中文文档托管在GitHub，fork自源仓库，且与原项目保持同步更新，另外增加了适合中国国内环境的新功能，为了方便使用，已经重新发布到pypi，重命名为isso-cn，姑且说是国内增强版吧。

英语水平有限，大部分是机翻而成，有些术语可能不是很准确，我自己测试过的功能会根据实际情况翻译。

Isso中文版本是0.12.3-rc1，新增的功能如下：

  • 支持了评论微信提醒、审核，且同时允许回复评论时邮件通知作者

二、自建Isso评论服务的记录

服务器系统：CentOS7.6
Python版本：2.7
依赖环境：

  • Python 2.7 or 3.4+ (+ devel headers)
  • SQLite 3.3.8 or later
  • C编译器

整个步骤很简单，安装好isso，简单的一个配置文件启动即可，当然想要更好的体验，您需要了解服务端配置文件和客户端配置文件。

强烈推荐先看一遍文档，英文、中文任君选择，以下是手动安装，官方也有Docker版。

2.1安装

$ sudo yum install python-devel sqlite
$ sudo pip install isso # 如果使用中文版的，请使用：sudo pip install isso-cn

安装成功，系统多一个isso命令，使用 -h/--help 查看命令帮助。

2.2服务端配置

您需要有一个目录来存储评论数据，即sqlite数据库文件。另外，您要准备好网址，Isso要针对网址设置CORS，不然会有跨域问题。

新建配置文件，比如： vim isso.cfg，最小化的内容如下示例：

[general]

; 数据库位置，注意检查权限，如果没有会自动创建。
dbpath = /data/isso/comments.db

; 网址，可以添加多个，比如 http 和 https
host =
    http://localhost:1234/
    http://example.tld/
    https://example.tld/

当然，这可以说是简陋，一个相对丰富的配置文件可能是这样的（这是本站博客的配置）：

[general]

#运行在多站点模式，name生效
name = blog
dbpath = /path/to/isso/comments.%(name)s.db
host =
    http://blog.saintic.com/
    https://blog.saintic.com/
max-age = 15m
#是的，Isso本身仅支持stdout、smtp提醒，这里是因为我用了中文的国内增强版，自己添加了微信提醒
notify = wechat
#评论回复时通过smtp发送邮件提醒
reply-notifications = true
gravatar = true
gravatar-url = https://www.gravatar.com/avatar/{}?d=identicon

[moderation]
#关闭了审核功能
enabled = false
purge-after = 30d

[smtp]
#使用的是腾讯企业邮箱
username = noreply@saintic.com
password = xxxxxx
host = smtp.exmail.qq.com
port = 465
security = ssl
#使用wechat提醒，to已经没用了；如果使用smtp提醒，每当有新评论时会发送邮件到to定义的邮箱。
to = staugur@saintic.com
from = "SaintIC Comment" <noreply@saintic.com>
timeout = 10


[markup]
#Markdown增加标签和属性
options = strikethrough, autolink, fenced_code, no_intra_emphasis
allowed-elements = img, i, b, u
allowed-attributes = src, width, height

[wechat]
#开启wechat提醒新增的配置，这是国内版才有的配置段。
tckey=xxx
sckey=xxx

参数解析就不放了，英文不错的可以参考官方文档，或者到中文文档-配置-服务端查阅。

2.3启动服务

配置无误，可以使用isso命令启动服务了。

启动服务，就是启动Web应用，在这里有两种运行模式：单站点和多站点。

单站点

即启动的isso只能解析一个配置文件，只为配置文件中的host提供服务，启动方法是：isso -c your.cfg run，使用的是 isso.run 模块，服务监听地址定义在your.cfg的server配置段。

不过这种启动方法只能用于低流量站点（最多每秒20个请求），很明显，适用于开发环境，不适合正式使用。

正式环境启动，请参考文档-部署一节，使用gevent、gunicorn、uwsgi等。

多站点

即启动的isso能解析多个配置文件（允许扫描某个目录下所有的cfg文件），其静态资源和API接口路径也有变化，启动方法是：

$ export ISSO_SETTINGS="/etc/isso.d/foo.example.cfg;/etc/isso.d/other.bar.cfg"
$ gunicorn isso.dispatch -b localhost:8080

使用的是 isso.dispatch 模块，run无法满足要求，服务监听地址由gunicorn定义，不读取配置。

不过gunicorn可以直接用于正式环境，当然实际使用时，gunicorn参数再实际调整，比如：

$ gunicorn -w 进程数 -b localhost:8080 isso.dispatch -k gevent --其他参数--

更多了解参阅文档-进阶-多站点。

所以，根据自己的实际使用要求选择模式和启动方法。

2.4配置Nginx

启动服务后，可以直接访问，不过针对正式环境，使用nginx代理isso是个好选择。

您可以为isso提供一个域名作为根访问：

server {
    listen [::]:80;
    listen [::]:443 ssl;
    server_name comments.example.tld;

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

或者作为某个已有域名的二级目录，这种情况要配置一个 X-Script-Name 头：

server {
    listen       [::]:80;
    listen       [::]:443 ssl;
    server_name  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 -t检测下语法，没问题重载nginx即可对外服务。

更多了解参阅文档-进阶-子路径。

2.5客户端配置

上述几个步骤都是在服务器进行的，完成后，服务器中运行着isso，通过nginx对外提供服务。

这时候，在网站需要评论的页面中放置用以显示评论框代码并引入isso的js即可完成初始化：创建评论框、加载css和评论数据等。

比如，博客详情页文章底部需要评论，在详情页中定义：

<!--在需要添加评论框的地方插入下面的 section 标签-->
<section id="isso-thread" data-title="默认标题自动检测，但是推荐您主动设置好"></section>
<!--然后引入 embed.min.js 插件-->
<script data-isso="/isso/" src="/isso/js/embed.min.js"></script>

这一段是简化的配置，实际上很多客户端很多参数可以调整，请参考文档-配置-客户端，这里我说明下src和data-isso参数。

  • src：

这个是embed.min.js的静态文件路径，多站点模式下，它是Isso服务根目录/js/embed.min.js；多站点模式下，它是Isso服务根目录/站点name/js/embed.min.js。

Isso服务根目录就是Nginx配置的域名，或者是二级目录；

多站点模式下，站点name就是服务端配置文件general配置段中的name值。

  • data-isso：

    这个是Isso服务的地址，发送API请求，这个值通常会自动检测，但是推荐您主动设置好。

如果没有异常，那么详情页底部会显示评论框，具体可以参考本站。

另外，像博客列表的场景下，仅仅要显示评论数量，在需要显示计数的位置插入下面一条 a 标签：

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

把 /my-uri.html 替换为你要计数的页面的 URI，然后引入计数插件count.min.js或embed.min.js任一即可。

PS：评论数参考文档翻译，本人也没实际测试。

2.6体验总结

本文安装的是isso-cn 0.12.3-rc1，且后续跟进升级，升级后版本体验在下面会带上版本提示。

  • [开启gravatar头像]

服务端isso配置文件要开启gravatar选项，客户端引用js配置data-isso-avatar=false，data-isso-gravatar=true才行，前者不设置为false时会同时显示两个头像。

  • [新评论提醒]

    会发送提醒，stdout或email或wechat，如果开启审核，邮件/微信消息中有activate链接，否则只有delete链接。

  • [评论回复通知]

    如果父评论开启回复，在子评论即便不开启也能收到回复

  • [nginx中，isso放到子目录，需要设置X-Script-Name头。]

  • [dispatch分发多站点，可以设置ISSO_SETTINGS为目录，isso会扫描目录下所有cfg作为配置文件]

  • [ip不精确问题，这是故意为之，客户端ip经过处理了，只显示ip段]

  • [如果一个页面没有评论，当加载 Isso 时，可以在浏览器控制台页面发现一个404错误。这是正常现象，意味着该页面还没有评论。]（引）

  • [目前的版本，在评论时如果遇到次数、频率限制或格式不符时，Isso 没有在页面进行提示，只能在浏览器控制台看到相关输出。]（引）(TODO)

2.7备份

就是直接备份sqlite数据库文件即可。

参考：

  1. https://zhangnew.com/isso-open-source-comment-system.html

  2. https://www.practicemp.com/2018/09/isso.html

三、国内增强版及周边

我fork的源仓库代码，目前翻译计划基本完成，后面陆续增加新功能，当然有的是国内特有，有的是使用优化。

已完成的周边：

  • 3.1 flask-pluginkit-isso，这是一个基于Flask-PluginKit的插件，用以提供前端部分的配置：显示评论框及引入js。

  • 3.2 本站开放平台编写新功能，允许在本站服务器上申请一个评论服务站点，避免使用独立服务器。

  • 3.3 微信审核部分单独拎出来，参考此文章


·End·