易于配置的变更日志网站Openchangelog

发表于 更新于 分类于 Waline： 阅读次数： 本文字数： 2.2k 阅读时长 ≈ 2 分钟
Openchangelog 能将您的变更日志 Markdown 文件转换为精美的产品更新。

什么是 Openchangelog ？

Openchangelog 能将您托管在 GitHub 或本地的 Markdown 文件呈现为漂亮的 Changelog 网站。

软件特点：

  • 易于自托管，只需一个配置文件
  • 用 Go 编写 → 轻量级
  • 各种集成，打开问题以请求新的集成
  • 自动 RSS 提要

安装

在群晖上以 Docker 方式安装。

老苏折腾时，最新版本为 0.1.0，tags 分为 0.1.0、0.1.0-litefs 和 0.1.0-sqlite，具体的差异未找到官方的说明；
本文发布时，最新版本为 0.2.1，注意修改对应的 tags；

下载镜像

1
2
3
4
5
6
7
8
# 新建文件夹 openchangelog 和 子目录
mkdir -p /volume1/docker/openchangelog/data

# 进入 openchangelog 目录
cd /volume1/docker/openchangelog

# 下载镜像
docker pull ghcr.io/jonashiltl/openchangelog:0.1.0

配置文件

创建一个openchangelog.yml配置文件

因为配置文件中使用了中文，记得用 UTF-8 格式保存

1
2
3
4
5
6
7
8
9
10
11
addr: 0.0.0.0:6001
local:
  filesPath: data
page:
  title: xxx软件
  subtitle: 产品更新说明
  logo:
    src: https://openchangelog.com/_astro/logo.0TXZ-ydY.svg
    width: 30px
    height: 30px
    link: https://laosu.tech
  • addr：侦听的地址和端口
  • filesPath：指定包含 Changelog Markdown 文件的目录的本地文件路径
  • title：标题显示在所有 Changelog 文章上方
  • subtitle：子标题，显示在标题下方
  • logo：logo 标志显示在页眉中

关于配置的更多的详细说明，可以参考官方文档：https://github.com/JonasHiltl/openchangelog#configuration

示例文件

文件名格式

变更日志文件的排序按文件名降序排列。建议在文件前面加上发布版本号

1
{version}.{title}.md

老苏准备了 2 个文件，分别是 v0.0.1.xxx.md 和 v0.0.2.xxx.md

内容格式

变更日志以 Markdown 编写，符合 Openchangelog 符合 CommonMark 0.31.2 规范

可以使用 Frontmatter 指定

  • title：以粗体标题显示在变更日志文章的顶部
  • description：显示在标题下方
  • publishedAt：采用 ISO 8601 格式，显示在变更日志文章旁边

v0.0.1.xxx.md 的内容如下：

1
2
3
4
5
6
7
---
title: xxx软件
description: 这是发布的第一个版本 
publishedAt: 2024-08-31
---

第一个版本

v0.0.2.xxx.md 的内容如下：

1
2
3
4
5
6
7
---
title: xxx软件
description: 这是发布的第二个版本 
publishedAt: 2024-09-01
---

第二个版本

docker cli安装

如果你熟悉命令行，可能用 docker cli 更快捷

1
2
3
4
5
6
7
8
# 运行容器
docker run -d \
   --restart unless-stopped \
   --name openchangelog \
   -p 6001:6001 \
   -v $(pwd)/openchangelog.yml:/etc/openchangelog.yml:ro \
   -v $(pwd)/data:/app/data
   ghcr.io/jonashiltl/openchangelog:0.1.0

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
version: '3.8'

services:
  openchangelog:
    image: ghcr.io/jonashiltl/openchangelog:0.1.0
    container_name: openchangelog
    restart: unless-stopped
    ports:
      - "6001:6001"
    volumes:
      - ./openchangelog.yml:/etc/openchangelog.yml:ro
      - ./data:/app/data

然后执行下面的命令

1
2
3
4
# 将 docker-compose.yml 和 openchangelog.yml 放入 openchangelog 根目录

# 一键启动
docker-compose up -d

运行

在浏览器中输入 http://群晖IP:6001 就能看到主界面

右上角可以通过 feed 订阅，来跟踪软件的版本变更

参考文档

JonasHiltl/openchangelog: Easy to configure & self hostable Changelog Website
地址：https://github.com/JonasHiltl/openchangelog

Markdown to a beautiful Changelog Site | Openchangelog
地址：https://openchangelog.com/

CommonMark
地址：https://commonmark.org/