Solo 用户指南

简介

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

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

安装

安装前先准备好 Java 环境，请使用 JDK8 或以上版本。war 包可以自行通过 maven 构建或者下载我们构建好的包。

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 就可以看到初始化向导界面了。如果要修改监听端口或者覆盖 latke.props 配置项，请参考 -h 帮助。

注意：上面的命令都是前台运行的，退出 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 不太熟悉，建议使用该方式
容器模式：可以和已有的程序一起部署在同一个容器中，这样可以节省内存

Docker

推荐使用 MySQL 作为数据库。如果你使用 H2，数据库文件将会自动保存在 docker 卷 中。你可以将你的
plugins & skins 同样备份到 docker 卷 中。升级之后通过备份还原。

docker exec -it solo cp -r /opt/b3log/solo/plugins /opt/b3log/backup/ && docker exec -it solo cp -r /opt/b3log/solo/skins /opt/b3log/backup/

环境变量	描述	可选值	默认值
DATABASE_TYPE	数据库类型, H2 或 MySQL	h2, mysql	h2
DATABASE_HOST	数据库地址或 IP, 针对 MySQL		localhost
DATABASE_PORT	数据库端口, 针对 MySQL		3306
DATABASE_NAME	数据库名称, 针对 MySQL		solo
DATABASE_USERNAME	数据库用户名, 针对 MySQL		root
DATABASE_PASSWORD	数据库密码, 针对 MySQL
SERVER_SCHMEA	Server schema	https,http	http
SERVER_NAME	服务器名称或域名		localhost
EMAIL_ADDRESS	电子邮件地址
EMAIL_PASSWORD	电子邮件密码
SMTP_HOST	SMTP 服务器地址		smtp.gmail.com
SMTP_PROT	SMTP 服务器端口		587
SMTP_SOCKETFACTORY_PORT	SMTP Socket Factory Port		465

细节配置

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

latke.properties：用于配置域名和端口，请配置为浏览器访问时候的域名和端口，更多细节请参考 Latke 配置剖析。另外，生产环境请务必配置 runtimeMode=PRODUCTION
local.properties：用于配置数据库，如果要使用 MySQL 的话请先手动建库（字符集使用 utf8mb4，排序规则 utf8mb4_general_ci），并注释掉 H2 相关属性同时打开 MySQL 相关属性
如果你想有人评论后收到邮件提醒，那需要配置一下 mail.properties，smtp 项可以找一下邮件服务提供商的帮助文档

另外，千万不要手动修改数据库，否则可能会引发各种莫名其妙的问题。

CDN 加速

我们提供了 Solo 静态资源的 CDN 加速，如果你正在使用 最新版本 的 Solo，可以在 latke.props 中加上如下配置：

staticServerScheme=https
staticServerHost=static-solo.b3log.org

皮肤

下载的 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 文件上传配置。

导入数据

MetaWeblog API

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

静态博客 /Markdown

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

备份

安全第一，血泪的教训 😢

war 包

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

配置文件

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

latke.properties
local.properties
mail.properties（如果修改过的话）

数据库

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

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

升级

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

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

其他一些特性

多用户

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

RSS/Atom

提供两种订阅供稿：Atom 1.0、RSS 2.0：

Atom: /rss.xml
RSS: /atom.xml

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

Sitemap

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

前台皮肤切换

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

使用场景举例：

在不安装 Solo 的情况下可以方便预览各个皮肤（在 Demo 上）
方便二次开发时集成切换皮肤
博主可以让访客体验到不同的效果，比如：这个皮肤好看？还是这个好看？

只有在首页（/）会取参数skin=xxx
如果带有就记录到 Cookie 里面，如果带有skin=default或皮肤不存在则清空 Cookie
如果要切换成后台默认的皮肤，在首页带参skin=default

站外相关文章

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

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

MetaWeblog API

MetaWeblog API 是用于离线管理文章的（比如使用 WLW），目前支持以下 APIs：

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

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

FAQ

初始化卡住

如果初始化向导页面已经正常显示，但是填完表单后点击“初始化”按钮后卡住，说明可能是 serverPort 、或者 serverHost 没有配置正确。域名和端口必须配置为浏览器访问时候的域名和端口，请注意端口并不是容器启动的监听端口；域名要注意是否带了 www，否则会引起跨域问题导致 JS 异常。

请在浏览器中 F12 查看网络请求来定位该问题。

如何引入自定义静态资源，比如 .mp3？

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

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

Solo 默认是使用内建的 flexmark 进行 md 渲染，可能对有的场景下的渲染效果不是很好。如果你想要获得更好的 md 渲染效果请参考这里。

移动端访问时皮肤不好看

可在 solo.props 中配置 mobile.skin 来指定移动端访问时的皮肤。请配置成目录名，区分大小写。

结语

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

简介

安装

独立模式

容器模式

独立 vs 容器

Docker

细节配置

CDN 加速

皮肤

NGINX 示例

初始化后

信息配置

签名档

参数设置

文件上传

导入数据

MetaWeblog API

静态博客 /Markdown

备份

war 包

配置文件

数据库

升级

其他一些特性

多用户

RSS/Atom

Sitemap

前台皮肤切换

站外相关文章

MetaWeblog API

FAQ

初始化卡住

如何引入自定义静态资源，比如 .mp3？

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

移动端访问时皮肤不好看

结语

欢迎来到黑客派

相关帖子

赞助商我要投放