Yuumi

从找最小值到旅行商问题：模拟退火算法的 Java 实现

Tue, 16 Jun 2026 00:00:00 GMT

1. 什么是模拟退火算法？

冶金学中的退火

模拟退火的退火源自冶金学术语退火。金属在加热后，原子能量变高，会离开原来的位置随机的在其他位置移动，退火时冷却速度较慢，使得原子有更多可能找到内能比原来位置更低的位置。

由此衍生的模拟退火算法

模拟退火算法的原理与金属退火相似，将待搜索空间内的每一点类比为一个金属原子，定义一个温度类比原子当前的能量，随机的选取一个邻居，计算原子会移动到当前邻居的概率，同时原子的温度会逐渐降低。随着温度降低到临界值，原子也会趋于一个全局的能量最低点。

在模拟退火算法中，需要进行如下的定义：

状态 & 邻态选择：模拟退火在每一步都需要基于当前的状态选取一个随机的邻态，并考虑是否要转移到这个邻态。
温度：模拟退火定义了一个温度变量，类比冶金退火中的当前温度。随着退火历程逐渐降低。
接收概率：是否从当前状态转移到邻态需要由接收概率定义。

[!TIP]

当邻态更优于当前状态时，自然会选择转移；而当邻态劣于当前状态时，由于原子自身具备的能量，还是有概率离开当前状态转移到邻态的。

这使得在高能量时，原子能更广泛的检索，而不是被困在当前的局部最优解，这也是模拟退火算法在爬山算法基础上的改进之处。

2. 什么时候用到模拟退火算法？

当问题满足下面的条件时，可以考虑使用模拟退火算法：

解空间特别大： 100个任务分配给10台机器；20个城市的旅行商问题；范围内的函数最值问题无法暴力枚举的问题
可以定义评分函数：可以明确判断两个方案哪个好任务分配问题可以通过总耗时判断；旅行商问题可以根据路线的总时间判断；函数最值问题可以通过比较函数在不同点的值判读
可以生成邻居解：交换随机两个任务执行的机器；随机交换旅行商路线中的两个城市；向左或向右移动随机的位置取值均可以生成一个邻居，进而比较邻居解和当前方案
存在局部最优方案：例如旅行商问题，当城市很多时，使用贪心算法容易陷入局部最优，而无法找到其他更优秀方案函数最值问题，函数图像可能有多个波峰，存在局部最优
允许得到近似最优解：模拟退火算法不保证全局最优，但能在可接受时间内得到足够好的近似解，适合问题规模大到无法求精确解的场景。

3. 模拟退火算法求解多峰函数最值

给定一个函数： $$ f(x) = \sin(x) + \sin(3x) + 0.1x^2 $$ ，求这个函数在 [0, 5]区间内的最大值。

函数图像如下：

package simulated_annealing;

import java.util.Random;

public class SimulatedAnnealingDemo {

    static Random random = new Random();

    // 定义函数（即条件2中的评分函数）
    static double target(double x){
        return Math.sin(x) + Math.sin(3 * x) + 0.1 * x * x;
    }

    // 定义扰动（即条件3中的获取邻居的方法）
    static double mutate(double curr){
    
        // 通过Math.min和Math.max把生成的邻居的范围限制在[0, 5]
        return Math.max(0, Math.min(curr + (random.nextDouble() - 0.5), 5));
    }


    // SA主逻辑
    public static void main(String[] args) {
    
        // 生成初始状态为当前状态，将当前状态的(x, y)设置为最佳状态
        double currX = random.nextDouble() * 6;
        double currY = target(currX);

        double bestX = currX;
        double bestY = currY;

        // 定义温度，最低温度阈值，冷却系数
        double temperature = 1000;
        double minTemperature = 0.0001;
        double coolingRate = 0.995;

        // 退火过程
        while (temperature > minTemperature) {
        
            // 调用扰动，获取当前状态的邻居态，并求解邻居态的值
            double nextX = mutate(currX);
            double nextY = target(nextX);

            double delta = nextY - currY;

            // 比较当前状态和邻居态的优劣
            if (delta > 0) {
            
                // 因为要求最大值，因此如果邻居态比当前状态更优，则接受
                currX = nextX;
                currY = nextY;
            } else {
            
                // SA的核心
                // 如果邻居态比当前状态更劣，则概率接受
                // 接收概率计算方法为：Math.exp(delta / temperature)
                double probability = Math.exp(delta / temperature);
                if (random.nextDouble() < probability) {
                    currX = nextX;
                    currY = nextY;
                }
            }

            // 如果新状态比最佳状态更好，则最佳状态替换为新的当前状态
            if (currY > bestY) {
                bestY = currY;
                bestX = currX;
            }

            // 温度降低
            temperature *= coolingRate;
            
            // 输出过程状态
            System.out.println(currX + " ==> " + currY);
        }
        
        // 输出最终结果
        System.out.printf("最优解: x = %.6f, f(x) = %.6f%n", bestX, bestY);
    }
}

运行结果如下：

5.0 ==> 2.1913635654939783
4.663310255727348 ==> 2.1650306949291216
4.932227738744374 ==> 2.247043141298705
4.8347081857352325 ==> 2.2783351972660553
4.609863083298898 ==> 2.083404663625435
4.795880597591812 ==> 2.2723253037868276
4.835759295604256 ==> 2.2783444866281934
5.0 ==> 2.1913635654939783
4.825175791571457 ==> 2.277886007069018
4.625396083392352 ==> 2.1093483021343054
... 此处省略很多行
0.6346640055673788 ==> 1.5781887948289557
0.6346640055673788 ==> 1.5781887948289557
0.6346640055673788 ==> 1.5781887948289557
0.6346640055673788 ==> 1.5781887948289557
最优解: x = 4.836988, f(x) = 2.278345

[!TIP] 其实我们可以观察到最后结果收敛到了(0.6346640055673788, 1.5781887948289557)，通过函数图像我们观察到这并不是全局最优解，而是一个局部最优解 退火末期 currX 卡在某个局部最优附近随机抖动是正常现象，但这不影响最终结果，因为算法全程都在用 bestX/bestY 跟踪目前见过的最优解，二者要分开看，不能拿 currX 最后停留的位置去判断算法有没有找到全局最优。

4. 模拟退火算法求解二维旅行商问题

简单描述下旅行商问题： 给定一系列城市的位置（有时候是城市间距离）, 请找出一条最短的路线，要求经过每条城市恰好一次，最终回到起点。

package simulated_annealing;

import java.util.Arrays;
import java.util.Random;

public class TravelingSalesmanProblemDemo {

    static Random random = new Random();

    // 定义城市位置
    static int[][] cities = {
            {0, 0},
            {3, 4},
            {6, 1},
            {7, 6},
            {2, 7}
    };

    // 计算城市间距离
    static double distance(int a, int b){
        int dx = cities[a][0] - cities[b][0];
        int dy = cities[a][1] - cities[b][1];
        return Math.sqrt(dx * dx + dy * dy);
    }

    // 定义函数（即条件2中的评分函数）
    static double totalDistance(int[] route){
        double total = 0;
        for (int i = 0; i < route.length - 1; i++) {
            total += distance(route[i], route[i + 1]);
        }
        total += distance(route[route.length - 1], route[0]);
        return total;
    }

    // 定义扰动（即条件3中的获取邻居的方法）
    // 此处扰动的方式是将当前路线中随机两个城市交换，生成新的路线
    static int[] mutate(int[] route){
        int[] next = route.clone();
        
        // 这里选择范围为random.nextInt(route.length - 1) + 1，因为 TSP 的路线本身是一个环路，起点选哪个城市不影响总距离，所以可以固定
        int i = random.nextInt(route.length - 1) + 1;
        int j = random.nextInt(route.length - 1) + 1;
        int tmp = next[i];
        next[i] = next[j];
        next[j] = tmp;
        return next;
    }

    // SA主逻辑
    public static void main(String[] args) {
    
        // 生成初始路线为当前状态，将当前路线和当前路线的总距离设置为最佳状态
        int[] currRoute = { 0, 1, 2, 3, 4 };
        double currDist = totalDistance(currRoute);

        int[] bestRoute = currRoute.clone();
        double bestDist = currDist;

        // 定义温度，最低温度阈值，冷却系数
        double temperature = 1000;
        double minTemperature = 0.0001;
        double coolingRate = 0.995;

        // 退火过程
        while (minTemperature < temperature){
        
            // 调用扰动，根据当前路线生成新的的邻居态路线，并求解邻居态的总路程
            int[] nextRoute = mutate(currRoute);
            double nextDist = totalDistance(nextRoute);

            double delta = nextDist - currDist;
            
            // 比较当前状态和邻居态的优劣
            if (delta < 0){
            
                // 因为要求最小值，因此如果邻居态的总距离比当前状态更小则是优，则接受
                currRoute = nextRoute;
                currDist = nextDist;
            } else {
            
                // SA的核心
                // 如果邻居态比当前状态更劣，则概率接受
                // 接收概率计算方法为：Math.exp(-delta / temperature)
                double probability = Math.exp(-delta / temperature);
                if (random.nextDouble() < probability){
                    currRoute = nextRoute;
                    currDist = nextDist;
                }
            }

            // 如果新状态比最佳状态更好，则最佳状态替换为新的当前状态
            if (currDist < bestDist){
                bestRoute = currRoute.clone();
                bestDist = currDist;
            }

            // 温度降低
            temperature *= coolingRate;
        }

        // 输出最终结果
        System.out.println("最优路线: " + Arrays.toString(bestRoute));
        System.out.println("最短距离: " + bestDist);
    }
}

运行结果如下：

最优路线: [0, 2, 3, 4, 1]
最短距离: 24.44307921765217

5. 模拟退火算法的思路

总结上面两个例子，我们可以发现模拟退火算法的大致思路是相通的，转换为伪代码如下：

public class Demo{

    static T 扰动方法(T 当前状态){
        T 邻居态 = 随机扰动(当前状态);
        return 邻居态;
    }

    static 评分 评分方法(T 状态){
        return 评分方法的具体逻辑(状态);
    }

    public static void main(String[] args) {
        定义初始状态currX, currY = 评分方法(currX)
        定义最佳状态bestX = currX, 最佳评分bestY = currY

        定义温度T，最低温度阈值TMin，冷却系数coolingRate

        while(T > TMin){
            nextX = 扰动方法(currX);
            nextY = 评分方法(nextX);

            delta = nextY - currY;
            if (nextX 优于 currX){
                currX = nextX;
                currY = nextY;
            } else if {
                double probability = Math.exp(-delta / temperature);
                // 这里是取delta还是-delta取决于求较优的比较方向

                if (random.nextDouble() < probability){
                    currX = nextX;
                    currY = nextY;
                }
            }

            // 这里的大于小于也是取决于求较优的比较方向
            if (currY > bestY) {
                bestY = currY;
                bestX = currX;
            }
        }

        // 输出最终结果
    }
}

6. 参数调优

模拟退火的效果很大程度上取决于三个参数：初始温度、冷却系数、终止温度。

// 定义温度，最低温度阈值，冷却系数
double temperature = 1000;
double minTemperature = 0.0001;
double coolingRate = 0.995;

1. 初始温度$$ T $$

根据接收概率公式：$$ P = e^{-\frac{\Delta}{T}} $$，我们不难发现：如果改变值 $$\Delta$$ 比当前温度 $$ T $$ 相比小几个量级时，$$ -\frac{\Delta}{T} $$ 趋近 0，总的$$ {P} $$ 趋近 1，即几乎所有变差的邻居都会被接受。 而如果初始温度 $$ T $$ 设置的和 $$\Delta$$ 差不多，甚至比 $$\Delta$$ 小，则会导致算法在刚起步时就几乎只接受比当前状态更好的邻居态，退化为普通的爬山算法。

[!TIP] 总结： 当初始温度$$ T $$设置的较大时，算法的早期会浪费时间在随机的游走上，虽然收敛变慢但是不会影响最终求解的质量。 当初始温度$$ T $$设置的较小时，算法会在一开始很难跳出局部最优解，效率快但是可能忽略全局最优解。 实践中可以这样估算：先粗略计算一下评分函数在邻居之间的典型差值大小（比如 TSP 里交换两个城市导致的总距离变化量级），让初始温度比这个量级大上一到两个量级。

2. 冷却系数

冷却系数控制温度下降的速度，越接近 1 降温越慢。 是否需要调整冷却系数，取决于问题规模。例子中的 TSP 只有 5 个城市，解空间很小，0.995 这个保守的降温速度完全够用；但如果城市数量上升到几十甚至上百个，解空间呈指数级增长，可能需要把冷却系数调得更接近 1（比如 0.999)，或者配合增加每个温度下的迭代次数，否则算法会过早收敛到一个较差的解。

[!TIP] 总结： 当冷却系数设置的较大时，温度很快跌到很低，算法还没来得及探索完解空间就早早收敛，容易陷入局部最优。 当冷却系数设置的较小时，探索更充分，更可能找到全局最优，但需要更多迭代次数才能让温度降到终止阈值，运行时间显著增加。

3. 终止温度

终止温度只是一个工程上的截断阈值，用来决定循环什么时候停止，本身没有特别的物理意义。 判断终止温度是否合理，可以看对应的接受概率: 当$$ T $$降到终止温度时，即使$$\Delta$$很小， $$ P = e^{-\frac{\Delta}{T}} $$也应该已经趋近于 0，这意味着此时算法基本只接受变好的邻居，跟普通爬山算法没有区别。如果终止温度设得过高，会导致算法在还有一定随机性的时候就提前停止，浪费了继续优化的机会。

7. 总结

回到文章标题——从找最小值到旅行商问题，这两个例子表面上差异很大：一个在连续的实数区间里找极值，一个在离散的排列组合里找最短路径。但如果把代码并排放在一起看，会发现两者用的是完全相同的退火框架，即##5中的伪代码。 两个例子也分别暴露了 SA 在两类问题上的不同表现。函数最值问题里，在运行结果那里其实说明了一个容易被忽略的点：算法运行过程中的"当前状态"和最终输出的"最佳状态"是两回事，温度降到很低后当前状态会卡在某个点上随机抖动，但真正有意义的答案始终是过程中记录的 bestX/bestY。TSP 问题里，由于解空间是离散的排列组合，邻居的定义（交换两个城市）直接决定了搜索能到达哪些状态，这也是为什么不同问题中"如何定义邻居"往往比调参数更影响最终效果。 当然，模拟退火不是万能的。它不保证找到全局最优解，只能保证大概率找到一个足够好的近似解；它对参数（初始温度、冷却系数、终止温度）比较敏感，调得不好效果可能还不如简单的贪心算法；遇到城市数量上百的 TSP 这类大规模问题，单纯依赖一次退火过程也往往不够，通常需要结合多次重启、自适应降温，或者和遗传算法、禁忌搜索等其他启发式方法配合使用。但对于中小规模、能够明确定义评分函数和邻居关系的优化问题，模拟退火胜在实现简单、思路直观，是一个性价比很高的起点。

Astro 博客添加 Waline 评论系统，Waline 的 docker 部署

Fri, 20 Mar 2026 00:00:00 GMT

Waline是一款轻量的，快速的，带后端的评论系统，官方提供了多种部署方案以及不同的数据存储可供选择

本文选择使用 MongoDB 作为数据存储服务， MongoDB 以及 Waline 均使用Docker部署

其他部署方案以及数据存储服务可以参考官方文档：Waline介绍

架构图如下

0. 准备工作

你需要准备：

docker环境, 用来部署 Waline 以及对应数据库
一个可运行的 astro 项目（可以参考 Astro项目搭建部署系列搭建一个 astro 博客项目）

1. Mongo 以及 Waline 的 Docker 部署

1. 创建 Docker 网络

用于让 Waline 通过容器名访问 MongoDB

docker network create waline-net

2. Docker 部署 MongoDB

docker run -d \
  --name mongo \
  --network waline-net \
  -e MONGO_INITDB_ROOT_USERNAME=DemoUsername \
  -e MONGO_INITDB_ROOT_PASSWORD=DemoPassword \
  -v /var/lib/mongo:/data/db \
  --restart unless-stopped
  mongo:6

[!TIP]

命令项详情

--name mongo 容器名称为mongo

--network waline-net 接入第一步创建的waline-net网络

-e MONGO_INITDB_ROOT_USERNAME=DemoUsername 设定初始用户的用户名

-e MONGO_INITDB_ROOT_PASSWORD=DemoPassword 设定初始用户的密码

-v ${pwd}/data:/data/db 挂载本地的data文件夹到容器的/data/db

mongo:6 选择镜像版本为mongo6

命令项	详情
--name mongo	容器名称为mongo
--network waline-net	接入第一步创建的waline-net网络
-e MONGO_INITDB_ROOT_USERNAME=DemoUsername	设定初始用户的用户名
-e MONGO_INITDB_ROOT_PASSWORD=DemoPassword	设定初始用户的密码
-v ${pwd}/data:/data/db	挂载本地的data文件夹到容器的/data/db
mongo:6	选择镜像版本为mongo6

3. Docker 部署 Waline

docker run -d \
  --name waline \
  --network waline-net \
  -p 8360:8360 \
  -e MONGO_DB=waline \
  -e MONGO_USER=DemoUsername \
  -e MONGO_PASSWORD=DemoPassword \
  -e MONGO_HOST=mongo \
  -e MONGO_PORT=27017 \
  -e MONGO_AUTHSOURCE=admin \
  -e JWT_SECRET=testsecret \
  --restart unless-stopped
  lizheming/waline

[!TIP]

命令项详情

--name waline 容器名称为waline

--network waline-net 接入第一步创建的waline-net网络

-p 8360:8360 指定端口为8360

-e MONGO_DB=waline 指定Waline使用MongoDB的数据库名为waline

-e MONGO_USER=DemoUsername 连接MongoDB的用户名，可以用2中设定的初始用户用户名，生产环境建议创建单独数据库用户

-e MONGO_PASSWORD=DemoPassword 连接MongoDB的密码，可以用2中设定的初始用户密码，生产环境建议创建单独数据库用户

-e MONGO_HOST=mongo 连接MongoDB的地址，因为接入了Docker网络因此使用MongoDB的容器名

-e MONGO_PORT=27017 连接MongoDB的端口

-e MONGO_AUTHSOURCE=admin 指定在MongoDB的admin数据库验证身份

-e JWT_SECRET=testsecret 一个随机长字符串，用于登录Waline时生成Token

lizheming/waline 选择Waline的镜像

命令项	详情
--name waline	容器名称为waline
--network waline-net	接入第一步创建的waline-net网络
-p 8360:8360	指定端口为8360
-e MONGO_DB=waline	指定Waline使用MongoDB的数据库名为waline
-e MONGO_USER=DemoUsername	连接MongoDB的用户名，可以用2中设定的初始用户用户名，生产环境建议创建单独数据库用户
-e MONGO_PASSWORD=DemoPassword	连接MongoDB的密码，可以用2中设定的初始用户密码，生产环境建议创建单独数据库用户
-e MONGO_HOST=mongo	连接MongoDB的地址，因为接入了Docker网络因此使用MongoDB的容器名
-e MONGO_PORT=27017	连接MongoDB的端口
-e MONGO_AUTHSOURCE=admin	指定在MongoDB的admin数据库验证身份
-e JWT_SECRET=testsecret	一个随机长字符串，用于登录Waline时生成Token
lizheming/waline	选择Waline的镜像

2. astro 项目接入 waline

[!TIP] 本部分主要参考了这篇文章：Fuwari 接入 Waline 评论系统 ~ 可选是否开启评论

1. Pnpm安装waline

pnpm add @waline/client

2. 在 src/components/comment 下新建文件 Waline.astro

---
import { commentConfig } from "../../config";

interface Props {
	path: string;
}

const config = {
	...commentConfig.waline,
	el: "#waline",
	path: Astro.props.path,
	dark: "html.dark",
	wordLimit: ["2", "300"],
};
---
<!-- Waline -->
<div class="relative w-full">
    <div id="waline"></div>
    <link rel="stylesheet" href="https://unpkg.com/@waline/client@v3/dist/waline.css" />
    <script type="module" is:inline define:vars={{ config }}>
        import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.js';
        init(config);
    </script>
</div>

[!TIP] path: Astro.props.path 这一行的作用是指明Waline使用文章的path区分不同文章下的评论，不会把不同文章的评论混淆

3. 在 src/components/comment 下新建文件 index.astro

---
import type { CollectionEntry } from 'astro:content'
import { commentConfig } from '@/config'
import Waline from './Waline.astro'
interface Props {
    post: CollectionEntry<'posts'>
}

const { id, data, slug } = Astro.props.post

const path = `/posts/${slug}`
const url = `${Astro.site?.href}${path}`
const comments = data.comments

let commentService = ''
if (commentConfig?.waline) {
    commentService = 'waline'
}
---
{ comments == true &&
    (
    <div class="card-base p-6 mb-5">
        {commentService === 'waline' && <Waline path={path} />}
        {commentService === '' && null}
    </div>
        )
    }

4. 修改 src/content/config.ts 中的类型约束

const postsCollection = defineCollection({
	schema: z.object({
		title: z.string(),
		published: z.date(),
		updated: z.date().optional(),
		draft: z.boolean().optional().default(false),
		comments: z.boolean().optional().default(true),
		description: z.string().optional().default(""),
		image: z.string().optional().default(""),
		tags: z.array(z.string()).optional().default([]),
		category: z.string().optional().nullable().default(""),
		lang: z.string().optional().default(""),

		/* For internal use */
		prevTitle: z.string().default(""),
		prevSlug: z.string().default(""),
		nextTitle: z.string().default(""),
		nextSlug: z.string().default(""),
	}),
});

5. src/types/config.ts 中添加CommentConfig和WalineConfig

export type BlogPostData = {
	body: string;
	title: string;
	published: Date;
	description: string;
	tags: string[];
	draft?: boolean;
	image?: string;
	category?: string;
	prevTitle?: string;
	prevSlug?: string;
	nextTitle?: string;
	nextSlug?: string;
	comments?: boolean;
};

export type ExpressiveCodeConfig = {
	theme: string;
};

export type CommentConfig = {
	waline?: WalineConfig;
};

type WalineConfig = {
	serverURL: string;
	login?: string;
};

6. src/config.ts中添加commentConfig

import type {
	ExpressiveCodeConfig,
	LicenseConfig,
	NavBarConfig,
	ProfileConfig,
	SiteConfig,
	CommentConfig
} from "./types/config";

export const commentConfig: CommentConfig = {
	waline: {
	    //这里填入#1 Docker宿主机的IP以及Docker中Waline容器的端口
		serverURL: 'http://localhost:8360', 
		login: 'enable'
	}
};

7. src/pages/posts/[...slug].astro中引入评论模块

---
import path from "node:path";
import License from "@components/misc/License.astro";
import Markdown from "@components/misc/Markdown.astro";
import I18nKey from "@i18n/i18nKey";
import { i18n } from "@i18n/translation";
import MainGridLayout from "@layouts/MainGridLayout.astro";
import { getSortedPosts } from "@utils/content-utils";
import { getDir, getPostUrlBySlug } from "@utils/url-utils";
import { Icon } from "astro-icon/components";
import { licenseConfig } from "src/config";
import ImageWrapper from "../../components/misc/ImageWrapper.astro";
import PostMetadata from "../../components/PostMeta.astro";
import { profileConfig, siteConfig } from "../../config";
import { formatDateToYYYYMMDD } from "../../utils/date-utils";
import Comment from "@components/comments/index.astro";

export async function getStaticPaths() {
	const blogEntries = await getSortedPosts();
	return blogEntries.map((entry) => ({
		params: { slug: entry.slug },
		props: { entry },
	}));
}

const { entry } = Astro.props;
const { Content, headings } = await entry.render();

const { remarkPluginFrontmatter } = await entry.render();

const jsonLd = {
	"@context": "https://schema.org",
	"@type": "BlogPosting",
	headline: entry.data.title,
	description: entry.data.description || entry.data.title,
	keywords: entry.data.tags,
	author: {
		"@type": "Person",
		name: profileConfig.name,
		url: Astro.site,
	},
	datePublished: formatDateToYYYYMMDD(entry.data.published),
	inLanguage: entry.data.lang
		? entry.data.lang.replace("_", "-")
		: siteConfig.lang.replace("_", "-"),
	// TODO include cover image here
};
---
<MainGridLayout banner={entry.data.image} title={entry.data.title} description={entry.data.description} lang={entry.data.lang} setOGTypeArticle={true} headings={headings}>
    <script is:inline slot="head" type="application/ld+json" set:html={JSON.stringify(jsonLd)}></script>
    <div class="flex w-full rounded-[var(--radius-large)] overflow-hidden relative mb-4">
        <div id="post-container" class:list={["card-base z-10 px-6 md:px-9 pt-6 pb-4 relative w-full ",
            {}
        ]}>
            <!-- word count and reading time -->
            <div class="flex flex-row text-black/30 dark:text-white/30 gap-5 mb-3 transition onload-animation">
                <div class="flex flex-row items-center">
                    <div class="transition h-6 w-6 rounded-md bg-black/5 dark:bg-white/10 text-black/50 dark:text-white/50 flex items-center justify-center mr-2">
                        <Icon name="material-symbols:notes-rounded"></Icon>
                    </div>
                    <div class="text-sm">{remarkPluginFrontmatter.words} {" " + i18n(I18nKey.wordsCount)}</div>
                </div>
                <div class="flex flex-row items-center">
                    <div class="transition h-6 w-6 rounded-md bg-black/5 dark:bg-white/10 text-black/50 dark:text-white/50 flex items-center justify-center mr-2">
                        <Icon name="material-symbols:schedule-outline-rounded"></Icon>
                    </div>
                    <div class="text-sm">
                        {remarkPluginFrontmatter.minutes} {" " + i18n(remarkPluginFrontmatter.minutes === 1 ? I18nKey.minuteCount : I18nKey.minutesCount)}
                    </div>
                </div>
            </div>

            <!-- title -->
            <div class="relative onload-animation">
                <div
                    data-pagefind-body data-pagefind-weight="10" data-pagefind-meta="title"
                    class="transition w-full block font-bold mb-3
                    text-3xl md:text-[2.25rem]/[2.75rem]
                    text-black/90 dark:text-white/90
                    md:before:w-1 before:h-5 before:rounded-md before:bg-[var(--primary)]
                    before:absolute before:top-[0.75rem] before:left-[-1.125rem]
                ">
                    {entry.data.title}
                </div>
            </div>

            <!-- metadata -->
            <div class="onload-animation">
                <PostMetadata
                        class="mb-5"
                        published={entry.data.published}
                        updated={entry.data.updated}
                        tags={entry.data.tags}
                        category={entry.data.category}
                ></PostMetadata>
                {!entry.data.image && <div class="border-[var(--line-divider)] border-dashed border-b-[1px] mb-5"></div>}
            </div>

            <!-- always show cover as long as it has one -->

            {entry.data.image &&
                <ImageWrapper id="post-cover" src={entry.data.image} basePath={path.join("content/posts/", getDir(entry.id))} class="mb-8 rounded-xl banner-container onload-animation"/>
            }


            <Markdown class="mb-6 markdown-content onload-animation">
                <Content />
            </Markdown>

            {licenseConfig.enable && <License title={entry.data.title} slug={entry.slug} pubDate={entry.data.published} class="mb-6 rounded-xl license-container onload-animation"></License>}

        </div>
    </div>

    <div class="flex flex-col md:flex-row justify-between mb-4 gap-4 overflow-hidden w-full">
        <a href={entry.data.nextSlug ? getPostUrlBySlug(entry.data.nextSlug) : "#"}
           class:list={["w-full font-bold overflow-hidden active:scale-95", {"pointer-events-none": !entry.data.nextSlug}]}>
            {entry.data.nextSlug && <div class="btn-card rounded-2xl w-full h-[3.75rem] max-w-full px-4 flex items-center !justify-start gap-4" >
                <Icon name="material-symbols:chevron-left-rounded" class="text-[2rem] text-[var(--primary)]" />
                <div class="overflow-hidden transition overflow-ellipsis whitespace-nowrap max-w-[calc(100%_-_3rem)] text-black/75 dark:text-white/75">
                    {entry.data.nextTitle}
                </div>
            </div>}
        </a>

        <a href={entry.data.prevSlug ? getPostUrlBySlug(entry.data.prevSlug) : "#"}
           class:list={["w-full font-bold overflow-hidden active:scale-95", {"pointer-events-none": !entry.data.prevSlug}]}>
            {entry.data.prevSlug && <div class="btn-card rounded-2xl w-full h-[3.75rem] max-w-full px-4 flex items-center !justify-end gap-4">
                <div class="overflow-hidden transition overflow-ellipsis whitespace-nowrap max-w-[calc(100%_-_3rem)] text-black/75 dark:text-white/75">
                    {entry.data.prevTitle}
                </div>
                <Icon name="material-symbols:chevron-right-rounded" class="text-[2rem] text-[var(--primary)]" />
            </div>}
        </a>
    </div>

    <Comment post={entry}></Comment>

</MainGridLayout>

3. 注册为管理员账号

浏览器访问:http://localhost:8360/ui/register 第一个注册并登录Waline的账号会被设置为管理员账号，使用该账号可以管理评论及账号

4. 其他的优化项

1. 在src/config.ts中，目前的写法宝暴露了IP端口，可以用Nginx反代的方式隐藏

在DNS解析添加子域名解析
使用CertBot添加Https证书 安装CertBot

sudo apt update
sudo apt install certbot -y

申请证书

sudo certbot certonly --standalone -d comments.selibert.xyz

在Nginx添加对应的server块

# ------------------------------
# Waline 评论系统（HTTPS）
# ------------------------------
server {
    listen 443 ssl;
    server_name comments.selibert.xyz;

    ssl_certificate /etc/letsencrypt/live/comments.selibert.xyz/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/comments.selibert.xyz/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://localhost:8360;  # Waline的IP端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header X-Forwarded-Proto https;
    }
}

2. （可选）可以默认隐藏登录按钮，让用户默认以匿名方式评论

---
import { commentConfig } from "../../config";

interface Props {
	path: string;
}

const config = {
	...commentConfig.waline,
	el: "#waline",
	path: Astro.props.path,
	dark: "html.dark",
	wordLimit: ["2", "300"],
};
---
<!-- Waline -->
<div class="relative w-full">
    <div id="waline"></div>
    <link rel="stylesheet" href="https://unpkg.com/@waline/client@v3/dist/waline.css" />
    <script type="module" is:inline define:vars={{ config }}>
        import { init } from 'https://unpkg.com/@waline/client@v3/dist/waline.js';
        init(config);
    </script>
</div>

<style is:inline>
.wl-btn {
    border-color: transparent;
    color: transparent;
    background-color: transparent;
    cursor: default;
}
</style>

Astro 博客 CI/CD 自动部署教程：使用 GitHub Actions 实现服务器自动发布

Wed, 15 Oct 2025 00:00:00 GMT

0. 准备工作

你需要准备

一台有公网IP的Linux服务器
一个可以运行的Astro项目

1. Linux上的部署

在Linux服务器上依次执行如下步骤：

1. 创建角色

创建Github部署时登录的角色

[!TIP] 推荐创建一个用户专门用于Github的CI/CD，不建议使用root角色进行CI/CD； 如果使用root需要配置Root的远程登录

sudo adduser github-ci

2. 创建文件夹

创建放置部署文件的文件夹并给CI角色赋权

mkdir /var/www/releases
chown -R github-ci:github-ci /var/www/releases

3. 安装openssh-server服务

先检查服务器上是否安装了ssh server

which ssh
which sshd

如果显示：

root@:~/.ssh# which ssh
/usr/bin/ssh
root@:~/.ssh# which sshd
/usr/sbin/sshd

表示已经安装了SSH服务，请跳转到； 如果未显示一个路径地址，则表示没有安装，需要安装，步骤如下：

Ubuntu / Debian

# 安装服务
sudo apt update
sudo apt install -y openssh-server
# 设置自启
sudo systemctl enable ssh
# 启动服务
sudo systemctl start ssh

CentOS / RHEL

# 安装服务
sudo yum install -y openssh-server
# 设置自启
sudo systemctl enable sshd
# 启动服务
sudo systemctl start sshd

4. 权限配置

# 先切换到CI角色
su - github-ci
# 生成SSH的公钥和私钥
chmod 700 ~/.ssh
ssh-keygen -t ed25519
# 查看~/.ssh文件夹下有没有authorized_keys文件，如果没有，则创建authorized_keys并赋权
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
# 将公钥（~/.ssh/id_ed25519.pub）的内容添加到 ~/.ssh/authorized_keys
grep "$(cat ~/.ssh/id_ed25519.pub)" ~/.ssh/authorized_keys || cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys

5. 安装Nginx服务

先查看服务器有没有安装Nginx

nginx -v

如果提示：command not found，则表示未安装Nginx，安装步骤如下：

Ubuntu / Debian

# 安装服务
sudo apt update
sudo apt install -y nginx
# 设置自启
sudo systemctl enable nginx
# 启动服务
sudo systemctl start nginx

CentOS / RHEL

# 安装服务
sudo yum install -y nginx
# 设置自启
sudo systemctl enable nginx
# 启动服务
sudo systemctl start nginx

验证安装情况：

systemctl status nginx

如果显示下列内容，则表示已经安装并启动了Nginx：

github-ci@:~/.ssh$ systemctl status nginx
● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/lib/systemd/system/nginx.service; disabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-03-23 15:58:11 CST; 1 week 2 days ago
       Docs: man:nginx(8)
    Process: 2379804 ExecReload=/usr/sbin/nginx -g daemon on; master_process on; -s reload (code=exited, status=0/SUCCESS)
   Main PID: 2330136 (nginx)
      Tasks: 3 (limit: 1834)
     Memory: 10.2M
        CPU: 18.277s
     CGroup: /system.slice/nginx.service
             ├─2330136 "nginx: master process /usr/sbin/nginx -g daemon on; master_process on;"
             ├─2379805 "nginx: worker process" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ""
             └─2379806 "nginx: worker process" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ""

6. 配置Nginx

修改Nginx的配置文件

user www-data;
worker_processes auto;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name _;
    
        root /var/www/current/dist;
        index index.html;
    
        location / {
            try_files $uri $uri/ /index.html;
        }
    }
}

修改完成后，运行检查：

sudo nginx -t

如果显示下列内容，则显示配置文件没有问题：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

另外，需要为CI用户添加配置允许无密码执行 nginx reload： 执行：sudo visudo 在文件尾部添加如下内容

github-ci ALL=(ALL) NOPASSWD:/bin/systemctl reload nginx

添加完成后键入：ctrl+o 显示 File Name to Write: /etc/sudoers，然后按Enter保存

2. Github上的配置：

根据如下路径配置Github远程登录服务器相关内容：

配置项及描述如下

配置项	描述
HOST	服务器的公网IP
USER	1-1中创建的角色名，示例为github-ci
SSH_KEY	1-4中生成的SSH私钥

3. 编写deploy.yml

在项目的根目录下，在.github/workflows/下创建deploy.yml，如果没有则创建。 deploy.yml文件内容如下：

name: Astro deploy
on:
  push:
    branches:
      - main # 这里是分支名称
jobs:
  build:
    runs-on: ubuntu-latest # 编译运行的平台
    steps: # 编译运行的步骤
      - name: 拉代码
        uses: actions/checkout@v4
      - name: Node环境
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: 安装 pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 9
          run_install: false
      - name: 安装依赖
        run: pnpm install --no-frozen-lockfile
      - name: 构建
        run: pnpm build
      - name: 上传文件
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_KEY }}
          source: "dist/"
          target: "/var/www/releases/${{ github.run_id }}"
      - name: 部署
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            mkdir -p /var/www/releases/${{ github.run_id }}
            ln -sfn /var/www/releases/${{ github.run_id }} /var/www/current
            systemctl reload nginx

4. 编写博文

在src/content/post文件夹下，创建一个新的Markdown文件，或者在控制台运行下列命令生成新的文件

pnpm new-post <filename>

在其中编写你的博文内容后，将markdown文件commit并push到Github后，在Github中查看编译运行情况：

左侧的Astro Deploy是deploy.yml中的name键的值 点击右侧的Commit Message可以查看这次Push对应的Action详情

这里可以看到每一步操作的日志信息，如果出现错误则进行对应的处理后重新部署

[!TIP] 如果你修改了服务器配置或者Github相关配置，没有修改代码但是又需要重新触发CI/CD，你有如下两种方案 

在Action左侧选择Astro Deploy，在右侧单击最后一次Push，然后在右侧点选Re-run all jobs 

你可以通过Commit并Push一次空的提交来触发CI/CD 命令为：git commit --allow-empty -m <commit message>

5. 回滚版本

你可以通过如下的命令将发布的版本回退到指定的版本：

ln -sfn /var/www/releases/旧版本ID /var/www/current

这个旧版本ID为github执行CI/CD的run-id github.run_id 是 GitHub Actions 为每次 workflow run 自动生成的唯一整数 ID，用于区分不同部署版本。 这一项是在deploy.yml中写到的：mkdir -p /var/www/releases/${{ github.run_id }} 在Action中，找到你需要回退到的那一次Push，在详情页面的URL可以找到这次CI/CD对应的run-id

Astro 博客搭建教程：框架选择与项目初始化完整指南

Fri, 10 Oct 2025 00:00:00 GMT

1. 技术选型

个人博客框架大致分为两类：

静态博客：例如 Astro、Hugo
动态博客：例如 WordPress，或者自己编写 Spring Boot + Vue / React

当然也可以在CSDN、稀土掘金之类的平台上直接上传文档。

静态博客和动态博客的运行方式完全不同：静态博客在写完文章后，通过构建生成静态HTML页面；动态博客则在每次访问时实时从服务器或数据库获取内容并渲染页面。以下是静态博客和动态博客的简单比较

静态博客和动态博客的优缺点

	静态博客	动态博客
性能	✅ 访问速度快	❌ 每次请求需查询数据库和渲染，速度可能较慢
成本	✅ 服务器要求低，可直接托管在平台	❌ 对服务器性能有一定要求
安全	✅ 无后端服务，注入风险低	⚠️ 若配置不当，可能存在 SQL 注入或其他安全风险
维护	✅ 更新文章只需上传文件，可结合 Git 自动构建	❌ 需要维护数据库及相关服务
功能	⚠️ 无动态能力，评论、用户登录需第三方支持	✅ 功能更丰富，可实现用户交互

基于个人网站的需求和机器性能的限制，本文选择使用Astro作为博客框架

2. 选择主题

Astro 官网的“资源-主题”页签页面提供大量免费和付费主题。 当然你也可以在其他推荐博文寻找合适主题，例如：

大部分主题的 GitHub 仓库都会提供部署好的 Demo 页面，方便预览效果。

本站使用的主题是Fuwari ::github{repo="saicaca/fuwari"}

3. 构建项目

第一步：fork上述的Fuwari项目

第二步：使用VSCode或者Webstorm将仓库克隆到本地

git clone https://github.com/your-username/fuwari.git

第三步：安装依赖

# 安装pnpm，如果已安装 pnpm 可跳过此步骤
npm install -g pnpm

# 安装依赖
pnpm install

第四步：启动项目

pnpm dev

这个时候就可以打开 http://localhost:4321/查看初试页面效果了

4. 修改配置

import type {
	ExpressiveCodeConfig,
	LicenseConfig,
	NavBarConfig,
	ProfileConfig,
	SiteConfig,
} from "./types/config";
import { LinkPreset } from "./types/config";

// 网站基本信息配置
export const siteConfig: SiteConfig = {
	title: "Fuwari", // 网站的标题
	subtitle: "Demo Site", // 网站的二级标题
	lang: "en", // 网站的使用语言
	themeColor: {
		hue: 250, // 默认主题色
		fixed: false, // fixed为true则隐藏调整主题色的选择器
	},
	
	// 主页图片相关
	banner: {
		enable: false, // 是否启用主页图片
		src: "assets/images/demo-banner.png", // 主页图文件路径，基于src文件夹
		position: "center", // 显示方式，可选项为：'top', 'center', 'bottom'。'center'为默认选项
		credit: {
			enable: false, // 显示图片的版权信息
			text: "", // 版权信息文本
			url: "", // 点击版权信息文本后跳转到的地址
		},
	},
	toc: {
		enable: true, // 博文右侧是否显示目录
		depth: 2, // 目录层级
	},
	
	// 网站图标
	favicon: [
		// 置空则显示默认图标
		// {
		//   src: '/favicon/icon.png',    // 网站图标图文件路径，基于public文件夹
		//   theme: 'light',              // (可选项) 可选项：'light' or 'dark', 仅在需要在亮色和暗色模式显示不同图标时配置
		//   sizes: '32x32',              // (可选项) 网站图标尺寸
		// }
	],
};

// 导航栏配置
export const navBarConfig: NavBarConfig = {
	links: [
		LinkPreset.Home,
		LinkPreset.Archive,
		LinkPreset.About,
		// 链接
		{
			name: "GitHub",
			url: "https://github.com/saicaca/fuwari",
			external: true, // 外部链接or内部链接
		},
	],
};

// 个人信息配置
export const profileConfig: ProfileConfig = {
	avatar: "assets/images/demo-avatar.png", // 头像图片地址。基于src文件夹
	name: "Lorem Ipsum", // 昵称
	bio: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", // 个人简介
	
	// 配置个人信息下方显示的链接
	links: [
		{
			name: "Twitter",            // 链接名称
			icon: "fa6-brands:twitter", // 链接图标，可以在https://icones.js.org找到更多的icon
			url: "https://twitter.com", // 链接地址
		},
		{
			name: "Steam",
			icon: "fa6-brands:steam",
			url: "https://store.steampowered.com",
		},
		{
			name: "GitHub",
			icon: "fa6-brands:github",
			url: "https://github.com/saicaca/fuwari",
		},
	],
};

// 博文下方的许可协议配置
export const licenseConfig: LicenseConfig = {
	enable: true,
	name: "CC BY-NC-SA 4.0",
	url: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
};

// markdown代码框主题配置
export const expressiveCodeConfig: ExpressiveCodeConfig = {
	theme: "github-dark",
};

重启项目后即可查看修改的内容

Intel Mac Mini 安装 Ubuntu（Intel 版）详细教程

Wed, 08 Oct 2025 00:00:00 GMT

0.准备工作

你需要准备:

一台MacMini(intel芯片)

因为Apple Silicon的Mac需要使用特定的Linux发行版本，而本人购入的是二手的MacMini(Late 2014)，型号为A1347，CPU为4代i7，因此本文不适用于M芯片的MacMini 在MacOS下，点击左上角苹果标志-关于本机即可查看CPU版本

一个U盘，建议16G及以上
Ubuntu系统镜像

1.数据备份

使用MacOS时间机器备份数据:使用“时间机器”备份你的 Mac
如果计划抹除MacOS使用Linux单系统，请先使用当前MacOS创建系统盘:创建可引导的 macOS 安装器
手动备份重要的数据到其他存储介质
如果是双系统，则需要提前使用磁盘工具创建空闲分区用来安装Linux

2.制作Linux启动盘

下载Linux系统镜像文件，本文选择的Ubuntu:下载页面，下载链接
- 受限于网络，可以选择其他镜像站下载，如齐鲁工业大学镜像站
- 你可以访问 Official CD Mirrors for Ubuntu，在China页签下找到其他的镜像站
下载启动盘工具，本文选择Ventoy:Github-Ventoy，官方下载页面，按照操作系统下载对应版本
解压Ventoy，双击exe文件启动
插入用来做启动盘的U盘，在Ventoy中选择对应的U盘，点击安装

安装前后
将1中下载的ISO文件放在U盘内

3.从启动盘安装Linux

重启MacMini，开机时按住Option(⌥)键，选择U盘启动
在Ventoy页面，上下选择上一步放入的ISO文件
磁盘分配：
- 首先，不可以删除和重建EFI分区（约 200MB，FAT32）！
- 如果你想要抹除MacOS，使用单Linux系统：
1. 删除除 EFI 分区以外的所有分区
2. 保留 EFI 分区，并设置挂载点为：/boot/efi；不要勾选格式化
3. 新建主分区，并设置挂载点为：/，设置文件系统为：ext4，勾选格式化
- 但是，如果你想要使用MacOS+Linux双系统:
1. 不要删除 macOS 分区
2. 选择空闲空间，新建主分区，并设置挂载点为：/，设置文件系统为：ext4，勾选格式化
3. 选择已有 EFI 分区，并设置挂载点为：/boot/efi，不要格式化
Ubuntu安装程序，按照安装程序设置地区、键盘布局、用户名密码等，等待安装完成

4.完成

至此系统安装完毕，可以使用你的Linux系统了