Solo 用户指南

小而美的博客系统，专为程序员设计

English

💡 简介

Solo 是一款小而美的开源博客系统，专为程序员设计。Solo 有着非常活跃的社区，可将文章作为帖子推送到社区，来自社区的回帖将作为博客评论进行联动（具体细节请浏览 B3log 构思 - 分布式社区网络）。

这是一种全新的网络社区体验，让热爱记录和分享的你不再感到孤单！

欢迎到 Solo 官方讨论区了解更多。同时也欢迎关注 B3log 开源社区微信公众号 B3log开源：

🗃 案例

https://ld246.com/top/solo

✨ 功能

• Markdown 编辑器支持三种编辑模式：所见即所得 / 即时渲染 / 分屏预览
• 标签聚合分类
• 自定义导航链接
• 随机文章 / 相关文章 / 置顶 / 更新提醒
• 自定义文章永久链接 / 签名档
• 配置站点 SEO 参数 / 公告 / 页脚
• 代码高亮 / 数学公式 / 流程图 / 五线谱
• 多皮肤，多端适配
• 多语言 / 国际化
• 友情链接管理
• 多用户写作，团队博客
• Hexo / Jekyll / Markdown 导入
• SQL / JSON / Markdown 导出
• Atom / RSS / Sitemap
• CDN 静态资源分离，可配置 jsDelivr CDN 分发
• 拉取 GitHub 仓库和自动备份
• 内置 HTTPS+CDN 文件存储
• 支持生成导出静态站点，用于发布 GitHub Pages

🎨 界面

开始使用

后台首页

编辑文章

选择皮肤

前台界面

🍱 皮肤

目前内置的皮肤如下，可点击进行预览：

• Bubble
• Casper
• Pinghsu
• Jane
• nijigen
• Medium
• 9IPHP
• Andrea
• Bruce
• Community
• favourite
• Finding
• i-nove
• metro-hot
• NeoEase
• next
• owmx-3.0
• timeline
• tree-house
• yilia

欢迎在这里推荐好看的皮肤，我们会尽量进行制作。

🛠️ 安装

Solo 支持“动静两用”：

• 动态博客：在服务器上搭建，进程常驻内存运行，在线使用
• 静态博客：在本地电脑运行，写作完成后生成导出静态站点

视频教程

• 本地 localhost 搭建
• 通过 IntelliJ IDEA 搭建
• 服务器上通过 Docker 搭建

更多视频教程陆续制作中，欢迎到 B 站关注我：报废程序员 D。

本地运行

本地运行主要用于试用或者生成静态站点，生成静态站点的用法请参考这里。

（视频演示教程请看这里）

下载最新的 Solo 包解压，进入解压目录执行：

• Windows: java -cp "lib/*;." org.b3log.solo.Server
• Unix-like： java -cp "lib/*:." org.b3log.solo.Server

如果你有 Java 开发环境，可参考这里通过源码构建运行（视频演示教程请看这里）。

Docker 部署

Docker 方式部署是动态博客用法，主要用于在服务器上部署动态博客。

（视频演示教程请看这里）

获取最新镜像

docker pull b3log/solo

启动容器

注意：对于如下命令，如果你不确定如何使用 \ 来进行换行，就不要换行了，一行内写完整条命令。

• 使用 MySQL

  手动建库（库名 solo ，字符集使用 utf8mb4 ，排序规则 utf8mb4_general_ci ）：

  create database solo default character set utf8mb4 collate utf8mb4_general_ci;
  create user 'root'@'127.0.0.1' identified by '123456';
  grant all privileges on *.* to 'root'@'127.0.0.1';
  flush privileges;
  

  启动容器：

  docker run --detach --name solo --network=host \
      --env RUNTIME_DB="MYSQL" \
      --env JDBC_USERNAME="root" \
      --env JDBC_PASSWORD="123456" \
      --env JDBC_DRIVER="com.mysql.cj.jdbc.Driver" \
      --env JDBC_URL="jdbc:mysql://127.0.0.1:3306/solo?useUnicode=yes&characterEncoding=UTF-8&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true" \
      b3log/solo --listen_port=8080 --server_scheme=http --server_host=localhost --server_port=
  

  为了简单，使用了主机网络模式来连接主机上的 MySQL。

• 使用 H2 Database

  docker run --detach --name solo --volume ~/solo_h2/:/opt/solo/h2/ --publish 8080:8080 \
      --env RUNTIME_DB="H2" \
      --env JDBC_USERNAME="root" \
      --env JDBC_PASSWORD="123456" \
      --env JDBC_DRIVER="org.h2.Driver" \
      --env JDBC_URL="jdbc:h2:/opt/solo/h2/db;MODE=MYSQL" \
      b3log/solo --listen_port=8080 --server_scheme=http --server_host=localhost --server_port=
  

启动参数说明：

• --listen_port：进程监听端口
• --server_scheme：最终访问协议，如果反代服务启用了 HTTPS 这里也需要改为 https
• --server_host：最终访问域名或公网 IP，不要带端口
• --server_port：最终访问端口，使用浏览器默认的 80 或者 443 的话值留空即可

完整启动参数的说明可以使用 -h 来查看。

日志配置

默认通过 log4j2 将日志打印到标准输出流，可以通过 docker logs solo 进行查看。如果需要覆盖 log4j 配置，可通过挂载文件实现：

--volume ~/log4j2.xml:/opt/solo/log4j2.xml

挂载第三方皮肤

如果需要使用第三方皮肤，可以挂载目录 skins，目录结构请参考原版 skins：

--volume ~/skins/:/opt/solo/skins/

版本升级

1. 拉取最新镜像
2. 重启容器

可参考这里编写一个重启脚本，并通过 crontab 每日凌晨运行来实现自动更新。

Docker Compose

请参考这里，感谢 @liumapp 提供。

NGINX 反代

upstream backend {
    server localhost:8080; # Solo 监听端口
}

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

    access_log off;

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

请务必配置：

proxy_set_header  Host $http_host;
proxy_set_header  X-Real-IP $remote_addr;

否则访问页面可能会出现“Latke 配置错误”或者样式异常；统计在线访客功能会不正常。

📜 文档

• 《提问的智慧》精读注解版
• 从零开始安装 Solo 博客（感谢 @InkDP 分享）
• Solo 用户指南
• Solo 从设计到实现
• Solo 皮肤开发指南
• 插件开发

🏘️ 社区

• 讨论区
• 报告问题

📄 授权

Solo 使用 木兰宽松许可证, 第 2 版 开源协议。

🙏 鸣谢

• jQuery：前端 JavaScript 工具库
• Vditor：浏览器端的 Markdown 编辑器
• Highlight.js：前端代码高亮库
• pjax：pushState + AJAX = pjax
• jsoup：Java HTML 解析器
• flexmark：Java Markdown 处理库
• Apache Commons：Java 工具库集
• Latke：以 JSON 为主的 Java Web 框架

初始化后

初始化成功后请务必查看自动发布的第一篇文章，里面有一些必要的操作，请务必完成。然后请到管理后台 -> 工具 -> 偏好设定中进行一下博客的细节配置。

信息配置

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

签名档

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

参数设置

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

• 列表显示方式：仅标题/标题 + 摘要/标题 + 正文
• 各种分页参数
• 文章更新提示：启用后一旦某篇文章更新过，则会在文章标题处显示“有更新”的提示，并且排序靠前
• 允许同步 GitHub 仓库：将文章数据自动导出到 GitHub 仓库，用于展示和备份

导入 Markdown

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

备份

安全第一，血泪的教训 😢

手动备份

• H2：备份 home 目录下的 solo_h2 文件夹
• MySQL：使用 MySQL 相关备份工具

社区端备份

可在工具 - 偏好设定 - 参数设置中勾选“备份所有文章到社区”，开启后将每隔 24 小时自动备份所有文章（包括草稿和加密文章）到社区，具体细节请参考 Solo 拉取 GitHub 仓库和自动备份。

GitHub 备份

可在工具 - 偏好设定 - 参数设置中填写 GitHub token，填写后将每隔 24 小时自动备份公开文章（不包括草稿和加密文章）到你的 GitHub 仓库 solo-blog，具体细节请参考 solo-blog 仓库同步功能回来了。

其他一些特性

多用户

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

RSS/Atom/Sitemap

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

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

不要用浏览器直接打开，请通过阅读器查看。另外，Solo 也能生成全站文章的 sitemap.xml。

前台皮肤切换

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

使用场景举例：

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

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

站外相关文章

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

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

FAQ

为什么要“捆绑”登录链滴社区账号？

Solo 和 Pipe 的定位是 B3log 分布式社区的博客端节点，并不是通常意义上的独立博客，所以账号体系需要进行统一，否则带来的问题会很多，这也是一路下来探索的，具体经历细节请看这里。

在 Solo v3 之前一直是独立账号体系，但经过长时间验证效果并不理想：

• 不方便，用户需要在社区端和博客端配置账号关联关系
• 不安全，账号的关联关系需要双向验证，如果不验证账号归属，会被冒名

这两个问题是矛盾的，所以为了解决它需要将账号在 B3log 网络中进行唯一化。一开始的设计方案是通过公私钥（类似区块链的钱包原理），但这个方案在现阶段过于复杂，用户使用门槛有点高所以暂时放弃了。公私钥的方案在星火项目里进行过测试验证，技术上应该没问题，以后的鱼塘项目可能会采用这个方案。

所以再次重申一下，Solo 和 Pipe 是 B3log 分布式社区的博客端节点。举个最容易理解的例子，这就好比某些厂商的软件，没有这个厂商的账号是用不了的。打通其他网络的方案是在博客端或者社区端接入其他网络的账号，目前已经在链滴社区上接入 GitHub 登录（可在账号设置中绑定），Solo 可通过 GitHub token 来将文章同步到自己的仓库，避免整个 B3log 网络过度封闭内卷。

最后，希望目前加入到 B3log 的用户是认可这个设计的，如果不认可的话其实就没必要加入使用了，节省自己时间同时也能保护 B3log。当然，不排除以后设计还会有所变化，欢迎参与思考讨论，谢谢。

服务器内存太小？

可考虑使用 Solo 的静态站点支持，本地写作完成后导出静态站点，发布 GitHub Pages 等服务。

如果还是想使用动态博客的话，可使用内嵌的 H2 数据库代替 MySQL。但建议还是进行内存升级，然后使用 Docker 和 MySQL 部署，这样不仅可以通过更新镜像进行平滑升级，还能使用 MySQL 相关工具更方便地进行数据库运维。

如何打 jar 包部署？

请在 pom.xml 中搜索 maven-assembly-plugin 的注释进行配置即可。请注意：使用 jar 运行不支持：

• 静态站点生成
• 可能存在其他未知问题

建议尽量不要打 jar 部署，服务器上请通过 Docker 部署。

获取社区文件存储服务上传凭证异常？

请参考这里进行配置。

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

请通过 NGINX 反代静态资源实现。

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

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

为什么在线访问计数一直都是 1？

在线访问计数是通过访问者 IP 去重的，每 10 分钟定时刷新一次。如果用了反向代理，请在代理配置部分加入客户端地址标头。比如 NGINX 需要加入如下配置：

proxy_set_header  X-Real-IP  $remote_addr;

如何插入广告展位？

可通过签名档、公告栏中插入 HTML、JS 代码来实现。

如何放置备案信息？

可通过在页脚配置中插入 HTML、JS 代码来实现。

如何使用 jsDelivr CDN 来加速？

启动时加入命令行参数：

--static_server_scheme=https
--static_server_host=cdn.jsdelivr.net
--static_server_port=
--static_path=/gh/88250/solo/src/main/resources

请注意，以上配置仅支持内置皮肤，如果挂载了第三方皮肤的话请按需调整。

Solo 会一直维护下去么？

Solo 的第一个版本发布于 2010 年，永不断更 😼

Solo 从第一版开始就支持平滑升级，从 v3.0.0 开始支持跨版本升级。在程序升级、数据兼容迁移方面我们做了很多工作。另外，Solo 还支持将数据导出成多种格式，所有的这些努力为的就是让大家能够免去后顾之忧，将精力更多放在创作和分享上。

结语

如果你在使用 Solo 过程中碰到问题或者有需求要提，欢迎跟帖，我们会在第一时间回复；如果你对 Solo 开发方面感兴趣，请参考 Solo 从设计到实现。