Kiblog

Kiblog 是一个基于 Spring Boot、Thymeleaf 和 SQLite 的轻量级个人博客系统。它支持文章发布与管理、Markdown 渲染、品牌文案外置配置，以及适合 jar + config 目录一起分发的部署方式。

当前版本：1.1.0

特性

• 首页、文章页、后台管理页统一支持深浅主题切换
• 文章内容支持 Markdown 渲染
• 支持脚注、任务列表、表格、KaTeX 数学公式
• 支持 Markdown 中的安全 HTML 扩展渲染
• 支持文章标签展示、搜索、分页
• 支持后台发布、编辑、删除文章
• 支持普通用户注册、登录和邮箱验证码验证
• 支持文章评论以及评论作者/管理员删除权限
• 支持文字头像、个人资料管理和管理员用户管理
• 使用 Spring Security Session、角色和 CSRF 保护写操作
• 支持站点品牌内容通过外部配置文件自定义
• 支持用户将头像等资源放在 config/assets/ 中单独管理

技术栈

• Java 25
• Spring Boot 4.0.6
• Spring MVC
• Spring Data JPA
• Thymeleaf
• SQLite

目录结构

Kiblog/
├─ config/
│  ├─ assets/
│  └─ kiblog.yml
├─ src/
├─ kiblog.db
├─ pom.xml
└─ README.md

运行要求

• JDK 25
• Maven 3.9+，或者直接使用仓库内置的 mvnw / mvnw.cmd

本地启动

1. 克隆并进入项目

git clone <your-repo-url>
cd Kiblog

2. 启动项目

Windows:

.\mvnw.cmd spring-boot:run

macOS / Linux:

./mvnw spring-boot:run

默认启动后访问：

• 前台首页：http://localhost:8080/
• 用户登录：http://localhost:8080/login
• 后台管理：http://localhost:8080/admin/dashboard

打包运行

1. 构建 Jar

Windows:

.\mvnw.cmd clean package

macOS / Linux:

./mvnw clean package

构建完成后，Jar 文件通常位于：

target/Kiblog-1.1.0.jar

2. 使用 jar + config 方式部署

推荐将以下内容放在同一目录下：

deploy/
├─ Kiblog-1.1.0.jar
└─ config/
   ├─ assets/
   └─ kiblog.yml

运行方式：

java -jar Kiblog-1.1.0.jar

项目会从当前工作目录下的 config/kiblog.yml 读取品牌、初始管理员和 SMTP 配置。Jar 与 config 目录应一起部署，缺少该文件时应用会拒绝启动并明确报告配置文件不存在。

配置说明

config/kiblog.yml

所有部署相关配置集中在该文件中。主要结构如下：

spring:
  mail:
    host: smtp.example.com
    port: 587
    username: no-reply@example.com
    password: your-app-password
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
          connectiontimeout: 5000
          timeout: 10000
          writetimeout: 10000

kiblog:
  brand:
    site-name: Kiblog
    home-title: 写给长期主义者的技术与生活记录
    home-subtitle: 从代码、产品和日常观察中挑出值得留存的部分，做成一份可反复翻阅的数字笔记。
    home-articles-title: 最新文章
    home-articles-description: 从最近写下的内容开始浏览，看看这段时间我在关注什么。
    about-name: Kiblog
    about-subtitle: 记录技术、产品与长期学习过程中的思考。
    about-description: 这里主要用来整理编程实践、产品体验和日常学习中的零散想法，希望把它们慢慢沉淀成更清晰、也更值得回看的内容。
    about-avatar-path: avatar.jpg

  admin:
    enabled: true
    username: admin
    password: CHANGE_ME_BEFORE_FIRST_START
    encoded-password: ""

  verification:
    from: no-reply@example.com
    expiration-minutes: 10
    resend-seconds: 60

修改配置后重启应用即可让品牌和 SMTP 设置生效。YAML 中包含邮箱密码及可能的管理员明文密码，部署时应限制该文件的读取权限。首次使用空数据库启动前必须将 CHANGE_ME_BEFORE_FIRST_START 改为至少 8 位的安全密码，否则应用会拒绝启动。

头像路径说明

about-avatar-path 按相对于 config/assets/ 目录的路径填写。

例如：

• avatar.jpg
• portraits/me.png

如果你的文件结构是：

config/
├─ assets/
│  └─ portraits/
│     └─ me.png
└─ kiblog.yml

那么应填写：

about-avatar-path: portraits/me.png

头像资源最终会通过 /assets/** 对外提供访问，config 目录中的其他文件不会被公开暴露。

SMTP 邮件

注册验证码通过 spring.mail 配置的 SMTP 服务发送。例如常用的 587 + STARTTLS 配置：

spring:
  mail:
    host: smtp.example.com
    port: 587
    username: no-reply@example.com
    password: your-app-password
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
          connectiontimeout: 5000
          timeout: 10000
          writetimeout: 10000

发件地址、验证码有效期和重发间隔通过 kiblog.verification 配置。验证码仍保存在进程内的线程安全 Map 中，应用重启后会失效。

初始管理员

当数据库中不存在任何 ADMIN 用户时，系统会根据 kiblog.admin 创建初始管理员：

kiblog:
  admin:
    enabled: true
    username: admin
    password: CHANGE_ME_BEFORE_FIRST_START
    encoded-password: ""

首次启动前必须替换示例密码，否则空数据库启动会失败。也可以清空 password 并在 encoded-password 中填写 BCrypt 密码。两者同时存在时优先使用 encoded-password。管理员创建后保存在 SQLite 中，后续修改 YAML 不会覆盖或重置已有管理员；请通过用户管理页修改现有管理员。

数据库

项目默认使用 SQLite，本地数据库文件为：

kiblog.db

数据库连接配置位于 src/main/resources/application.properties：

spring.datasource.url=jdbc:sqlite:kiblog.db
spring.datasource.driver-class-name=org.sqlite.JDBC
spring.jpa.hibernate.ddl-auto=update

后台说明

后台页面入口：

/login

登录成功后可以进入后台管理页，进行以下操作：

• 发布文章
• 编辑文章
• 删除文章
• 实时预览 Markdown 渲染效果

后台采用 Spring Security Session 认证，只有 ADMIN 角色可以访问。POST、PUT、DELETE 请求均启用 CSRF 防护。

用户和评论

• 注册时用户名和邮箱必须唯一，验证码验证通过后创建 USER 角色账号
• 用户名用于登录，邮箱用于注册验证和更换邮箱时的所有权验证
• 登录用户可在 /account 修改用户名、头像文字、邮箱和密码
• 头像文字为空时使用用户名前两个字符，配置超过两个字符时自动截取
• 所有人都可以查看评论，登录用户可以发表评论
• 评论作者可以删除自己的评论，管理员可以删除任意评论
• 管理员可在 /admin/users 查看和管理用户角色、状态与公开资料
• 用户 ID 和密码哈希不会通过用户接口或管理接口返回

Markdown 能力

Kiblog 当前支持以下内容渲染：

• 标题、段落、引用、代码块
• 标签页风格的任务列表
• 脚注
• 表格与横向滚动优化
• KaTeX 数学公式
• details/summary 折叠面板
• 音视频与 iframe 嵌入
• 安全的 HTML 扩展内容渲染

说明：

• 当净化器可用时，Markdown 中的 HTML 扩展内容会经过安全清洗后渲染
• 当净化器不可用时，系统会退回到更保守的安全模式，不直接渲染原始 HTML

安全说明

• config/ 目录不会被整体暴露
• 仅 config/assets/ 会通过 /assets/** 暴露给前台，用于头像等静态资源
• Markdown 渲染链已加入 HTML 安全清洗
• 密码使用 BCrypt 保存，管理接口按 ADMIN 角色保护
• 所有写操作保留 Spring Security CSRF 防护

开发说明

编译检查：

Windows:

.\mvnw.cmd -q -DskipTests compile

macOS / Linux:

./mvnw -q -DskipTests compile

完整测试：

.\mvnw.cmd clean verify

上线检查

• 修改 config/kiblog.yml 中的初始管理员占位密码
• 配置可用的 SMTP 服务并实际验证验证码邮件
• 限制 config/kiblog.yml 和 kiblog.db 的文件读取权限
• 定期备份 kiblog.db 与 config/assets/
• 通过反向代理启用 HTTPS，并只向公网开放 HTTPS 入口
• 确保进程工作目录中包含与 Jar 同级的 config/kiblog.yml

可自定义内容

推荐开放给使用者自行修改的内容包括：

• config/kiblog.yml 中的品牌、初始管理员与 SMTP 配置
• config/assets/ 中的头像文件
• kiblog.db 中的文章数据

License

该项目使用MIT LICENSE，详情请参阅 LICENSE 文件。