Isso中文文档:自建Isso评论服务及其国内增强版功能介绍

 应用服务  python  isso  开源项目   2019-11-30 20:12 

一、概述

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 本站开放平台编写新功能,允许在本站服务器上申请一个评论服务站点,避免使用独立服务器。


点赞 打赏
取消

感谢您的支持,我会继续努力的!

扫码支持
扫码打赏,你说多少就多少

打开支付宝扫一扫,即可进行扫码打赏哦