Solo 用户指南

简介

Solo 是一款一个命令就能搭建好的 Java 开源博客系统,并内置了 15+ 套精心制作的皮肤。除此之外,Solo 还有着非常活跃的社区,文章分享到社区后可以让很多人看到,产生丰富的交流互动。

Solo 的第一个版本发布于 2010 年,至今已经非常成熟稳定,请放心使用 smirk_cat

安装

安装前先准备好 Java 环境,请使用 JDK8 或以上版本。Solo 提供了两种部署模式,分别是独立模式和容器模式。数据库默认是使用内嵌的 H2 数据库,也支持 MySQL,稍后会详细介绍。

对于系统内存要求,最低 512M,推荐 1G。

独立模式

独立模式使用内嵌的 Jetty 容器进行部署,解压 war 包后仅需要一个命令就能启动:

  • Windows: java -cp WEB-INF/lib/*;WEB-INF/classes org.b3log.solo.Starter
  • Unix-like: java -cp WEB-INF/lib/*:WEB-INF/classes org.b3log.solo.Starter

启动正常的话打开浏览器访问 http://localhost:8080 就可以看到初始化向导界面了。

注意:上面的命令都是前台运行的,退出 shell 后会被终止。比如 Linux 上不中断运行需要使用 nohup,比如这样 nohup java -cp WEB-INF/lib/*:WEB-INF/classes org.b3log.solo.Starter >/dev/null 2>&1 &

容器模式

使用 Jetty 或者 Tomcat(版本要求至少 9)进行部署,将 war 包放到容器的 webapps 目录下即可。访问时需要带上下文路径(容器自动解压 war 后的目录名),比如 http://localhost:8080/solo

独立 vs 容器

两种模式各有千秋:

  • 独立模式:一个命令就能启动,如果你对 Java Web 不太熟悉,建议使用该方式
  • 容器模式:可以和已有的程序一起部署在同一个容器中,这样可以节省内存

细节配置

主要的配置文件有两个,它们都存放在 WEB-INF/classes 目录下。

  • latke.properties:用于配置域名和端口,请配置为浏览器访问时候的域名和端口
  • local.properties:用于配置数据库,要切换为 MySQL 的话请在这里配置

更多细节请参考 Latke 配置剖析

如果你想有人评论后收到邮件提醒,那需要配置一下 mail.properties,smtp 项可以找一下邮件服务提供商的帮助文档。

皮肤

下载的 war 包中自带了所有官方皮肤,如果你是自己拉源码构建的,可以到这里下载皮肤。

皮肤放到 skins 目录下后重启服务,在工具 -> 偏好设定 -> 皮肤中选择使用即可。

NGINX 示例

upstream backend {
    server localhost:8080; # Tomcat/Jetty 监听端口
}

server {
    listen       80;
    server_name  88250.b3log.org; # 博客域名

    access_log off;

    location / {
        proxy_pass http://backend$request_uri;
        proxy_set_header  Host $host:$server_port;
        proxy_set_header  X-Real-IP  $remote_addr;
        client_max_body_size  10m;
    }
}

相应的 latke.props 配置:

serverScheme=http
serverHost=88250.b3log.org
serverPort=80

初始化后

初始化成功后强烈建议到管理后台 -> 工具 -> 偏好设定中进行一下配置。

信息配置

  • 博客基本信息:标题、子标题、SEO 信息
  • HTML head:可以配置脚本,比如百度统计
  • 公告:可以使用 HTML 和脚本进行配置
  • 页脚:主要用来放备案信息,也可以使用 HTML 和脚本进行配置

签名档

最多可以配置 3 个签名档,发布文章的时候选择一个使用,可以使用 HTML 和脚本进行配置。

参数设置

下面是一些比较有特色或重要的参数:

  • 编辑器类型
  • 列表显示方式:仅标题 / 标题 + 摘要 / 标题 + 正文
  • 各种分页参数
  • 文章更新提示:启用后一旦某篇文章更新过,则会在文章标题处显示“有更新”的提示,并且排序靠前
  • 允许注册:开放注册后其他人可以注册成为“访客用户”,方便评论时不用每次都填写基本信息。管理员可以在用户管理中看到当前的所有用户,并可以改变用户角色

七牛

目前 Solo 只支持将文件上传到七牛上,请参考 Solo 文件上传七牛

关于支持上传文件到本地服务器的特性还在讨论中,如果你也有这个需求,请来这里参与讨论。

导入数据

MetaWeblog API

如果你之前使用的系统支持这个特性,可以先用客户端工具导出文章到本地,然后再导入 Solo,可参考下面的 MetaWeblog API 配置。

静态博客 /Markdown

请参考 Solo 支持 Hexo/Jekyll 数据导入

备份

安全第一,血泪的教训 cry

war 包

如果你修改过代码请记得备份整体的 war 包,如果没有修改过则只用备份下面的配置文件。

配置文件

进行版本升级时需要,建议备份 WEB-INF/classes/ 目录下的三个文件

  • latke.properties
  • local.properties
  • mail.properties(如果修改过的话)

数据库

  • H2:备份用户 home 目录下的 solo_h2 文件夹
  • MySQL:使用 MySQL 相关备份工具,或者到博客后台工具 -> 其他中进行 SQL 导出

强烈建议定时备份数据!!!

升级

使用在跑着的老版本的配置文件覆盖新版本 war 中的(或者重新再配置一次),然后直接部署就好,启动时会自动进行升级。要确认升级是否成功的话留意一下日志,或者查看 option 表中的 version 行。

注意:不能进行跨版本升级,建议紧跟我们的发布步伐 sweat_smile 下面是两位用户升级 Solo 的经验分享,请参考一下:

其他一些特性

多用户

可以几个用户同时使用一个博客发布文章,主要用在团队博客这个场景。权限方面做了简单隔离,非管理员用户可以看到其他用户的博文 / 评论列表,但是不能进行操作。

RSS/Atom

提供两种订阅供稿:Atom 1.0、RSS 2.0,分别可以对博客文章列表、标签 - 文章列表进行供稿:

  • 博客文章列表
    • Atom: /blog-articles-feed.do
    • RSS: /blog-articles-rss.do
  • 标签 - 文章列表
    • Atom: /tag-articles-feed.do?oId=${tagId}
    • RSS: /tag-articles-rss.do?oId=${tagId}

浏览器直接打开可能会出现编码问题,可使用阅读器查看。

Sitemap

自动生成全站文章的 sitemap.xml,有利于 SEO。

前台皮肤切换

通过 URL 带参(比如 http://demo.b3log.org/?skin=finding)来确定渲染使用的皮肤。

使用场景举例:

  • 在不安装 Solo 的情况下可以方便预览各个皮肤(在 Demo 上)
  • 方便二次开发时集成切换皮肤
  • 博主可以让访客体验到不同的效果,比如:这个皮肤好看?还是这个好看?
  1. 只有在首页(/)会取参数skin=xxx
  2. 如果带有就记录到 Cookie 里面,如果带有skin=default或皮肤不存在则清空 Cookie
  3. 如果要切换成后台默认的皮肤,在首页带参skin=default

站外相关文章

“站外相关文章”指的是其他人使用 Solo 发布的文章,该文章含有与你的文章相同的标签。该功能主要是为了加强各个 Solo 博客之间的互动性,让博客访问者可以更有效地访问到相关的内容。

这是 B3log 构思 的一部分实现,请大家积极参与进来 heartbeat

MetaWeblog API

MetaWeblog API 是用于离线管理文章的(比如使用 WLW),目前支持以下 APIs:

  • blogger.getUsersBlogs – 获取博客
  • metaWeblog.getCategories – 获取标签列表
  • metaWeblog.getRecentPosts – 获取最新文章列表
  • metaWeblog.getPost – 获取文章
  • metaWeblog.newPost – 发布文章 / 保存草稿
  • metaWeblog.editPost – 编辑文章
  • blogger.deletePost – 删除文章

配置地址:/apis/metaweblog,用户名 / 密码:管理员的口令

FAQ

初始化卡住

如果初始化向导页面已经正常显示,但是填完表单后点击“初始化”按钮后卡住,说明可能是 serverPort 没有配置正确,这个端口需要配置为浏览器访问时候的端口,而不是容器启动的监听端口。

如何引入自定义静态资源,比如 .mp3?

请参考 WEB-INF/static-resources.xml 中的配置,加入自定义资源的路径匹配后重启。

如何获得更好的 Markdown 渲染效果?

Solo 默认是使用内嵌的 flexmark 进行 md 渲染,这个项目还比较新,对有的场景下的 md 渲染效果处理不是很好。如果你想要获得更好的 md 渲染效果需要这样做:

  1. 安装 Node.js
  2. 安装 marked:npm install marked --save
  3. 在 Solo 目录下执行 node js/marked/http.js 以启动 marked(你可能需要 nohup)。marked 需要监听 8250 端口,所以启动前请确认该端口可用
  4. 重启 Solo 后就会使用 marked 作为 markdown 渲染引擎了

结语

如果你在使用 Solo 过程中碰到问题或者有需求要提,欢迎跟帖,我们会在第一时间回复,让我们一起度过一段美好的时光。另外,如果你想对 Solo 进行定制开发,请参考 Solo 开发指南