{ "version": "https://jsonfeed.org/version/1", "title": "vv", "home_page_url": "https://devvv.cn/blog", "description": "feedId:42215011978385457+userId:41840353283325416", "items": [ { "id": "https://devvv.cn/blog/color-alpha-contrast-table", "content_html": "
不透明度十六进制值
100%FF
95%F2
90%E5
85%D8
80%CC
75%BF
70%B2
65%A5
60%99
55%8C
50%7F
45%72
40%66
35%59
30%4C
25%3F
20%33
15%21
10%19
5%0C
0%00
\n

如果设计给出的是透明度，就用100-透明度， 就是不透明度。

", "url": "https://devvv.cn/blog/color-alpha-contrast-table", "title": "透明度对照表", "summary": "透明度对照表", "date_modified": "2026-04-01T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "透明度" ] }, { "id": "https://devvv.cn/blog/for-dkplayer-16k-adaption-page-process", "content_html": "

前言​

\n

最近需要集成视频播放功能，但是项目又已经集成了 FFmpeg，因此采用 ExoPlayer 播放器，而 DKPlayer 在 ExoPlayer 基础上做了一些封装，方便使用。但是 DKPlayer 没有适配 16k 页面，因此需要自己编译一个版本。

\n

\"16k

\n

步骤​

\n

通过上述截图发现，没适配 16k Page Size 只有的 librtmp-jni.so。

\n

这个库位于：https://github.com/ant-media/LibRtmp-Client-for-Android

\n
git clone https://github.com/ant-media/LibRtmp-Client-for-Android.git
cd LibRtmp-Client-for-Android
bash
\n

新建 local.properties 文件：

\n
touch local.properties

# 添加 sdk.dir
sdk.dir=/home/vv/android/SDK
bash
\n

执行编译：

\n
./gradlew assembleRelease
bash
\n

\"编译成功\"

\n

编译后的 .aar 文件位于：

\n
/home/vv/android/work/demo/LibRtmp-Client-for-Android/rtmp-client/build/outputs/aar
text
\n

进入这个目录，提取 .aar，.so 文件位于其下。

\n

检查是否适配成功​

\n

用下面的命令检查一下 .so 文件：

\n
# 使用NDK中的llvm-objdump工具检查（路径需替换为你自己的NDK路径）
/home/vv/android/SDK/ndk/25.2.9519653/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-objdump -p librtmp-jni.so | grep LOAD
bash
\n

如何判断结果：

\n\n

\"检验结果\"

\n

替换到自己项目​

\n

把对应的 .so 文件复制到 libs 目录下：

\n

\"libs

\n

在 build.gradle.kts 中添加：

\n
android {
    
    defaultConfig {
        ndk {
            abiFilters += listOf(\"arm64-v8a\", \"x86_64\")
        }
    }

    sourceSets {
        getByName(\"main\") {
            jniLibs.srcDirs(arrayOf(\"libs\"))
        }
    }
    
    packaging {
        jniLibs {
            useLegacyPackaging = false
        }
        jniLibs.pickFirsts.addAll(
            arrayOf(
                \"lib/x86/libc++_shared.so\",
                \"lib/x86_64/libc++_shared.so\",
                \"lib/armeabi-v7a/libc++_shared.so\",
                \"lib/arm64-v8a/libc++_shared.so\",
                // DKPlayer 16k page 适配需要
                \"lib/arm64-v8a/librtmp-jni.so\",
                \"lib/x86_64/librtmp-jni.so\",
//                \"lib/armeabi-v7a/librtmp-jni.so\",
            )
        )
    }
}
kts
\n

常见报错​

\n

Java 版本太高报错，需要降级：

\n

\"报错\"

\n

打开 Android Studio 中的 Project Structure -> SDK Location -> Java Location 中 -> Gradle Settings：

\n

下载完 JDK11，修改 Java 环境变量：

\n
nano ~/.bashrc
# 把 JAVA_HOME 改为 JDK11 的路径

source ~/.bashrc

java -version

# 再次执行
./gradlew assembleRelease
bash
", "url": "https://devvv.cn/blog/for-dkplayer-16k-adaption-page-process", "title": "为 DKPlayer 适配 16k 页面", "summary": "为 DKPlayer 适配 16k 页面", "date_modified": "2026-04-01T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Android", "DKPlayer" ] }, { "id": "https://devvv.cn/blog/docker-install-step-by-step", "content_html": "

完全清理 Docker 配置​

\n
# 1. 删除所有 Docker 相关的源文件
sudo rm -f /etc/apt/sources.list.d/docker*.list
# 2. 清除残留的列表文件
sudo rm -f /var/lib/apt/lists/*docker*
# 3. 移除可能存在的旧 Docker 包
sudo apt remove -y docker docker-engine docker.io containerd runc
bash
\n

安装 Docker​

\n
# 更新系统并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget
# 安装Docker
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable\" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
# 添加当前用户到docker组（避免每次使用sudo）
sudo usermod -aG docker $USER
newgrp docker  # 立即生效或重新登录
# 验证安装
docker --version
docker compose version

sudo systemctl enable docker # 开机自启

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  \"registry-mirrors\": [
    \"https://docker.m.daocloud.io\"
  ]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker
bash
", "url": "https://devvv.cn/blog/docker-install-step-by-step", "title": "docker 安装", "summary": "docker 安装", "date_modified": "2026-04-01T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "docker" ] }, { "id": "https://devvv.cn/blog/fast-look-system-info-by-fastfetch", "content_html": "

Ubuntu：

\n
sudo apt install fastfetch
bash
\n

Windows：

\n
winget install fastfetch
bash
\n

启动：

\n
fastfetch
fastfetch -c all.jsonc
bash
", "url": "https://devvv.cn/blog/fast-look-system-info-by-fastfetch", "title": "快速查看系统信息", "summary": "快速查看系统信息", "date_modified": "2026-03-31T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "fastfetch" ] }, { "id": "https://devvv.cn/blog/build-ffmpegkit-for-android", "content_html": "

目标​

\n

源码：https://github.com/arthenica/ffmpeg-kit

\n

16k 适配版本（编译需要 java21）：https://gitee.com/weijun233/ffmpeg-kit-android-16KB

\n

GNU Config：https://github.com/arthenica/gnu-config

\n

直接下载最新源码：ffmpeg-kit-main.zip

\n

下载 GNU Config：gnu-config-master.zip

\n

最终自己编译一份 .aar 文件。

\n

整体流程概览​

\n
    \n
  1. 准备环境：安装必要工具，配置 Android SDK/NDK 环境变量。
    2. \n
  2. 执行构建：运行 android.sh 脚本。
    3. \n
  3. 获取产物：在 prebuilt 目录下找到生成的 .aar 文件。
    4. \n
  4. 集成项目：将 .aar 文件放入项目并添加依赖。
    5. \n
\n
\n

详细步骤​

\n

第一步：准备工作（环境配置）​

\n

在开始编译前，需要确保开发环境满足条件。

\n
    \n
  1. \n

    安装必要工具：Ubuntu 24.04 LTS ：

    \n
    sudo apt update

    sudo apt install autoconf automake libtool pkg-config curl git doxygen nasm cmake gcc gperf texinfo yasm bison autogen wget autopoint meson ninja-build ragel groff gtk-doc-tools 'libtasn1*'
    bash
    \n

    注：这些工具是编译 FFmpeg 及其依赖库所必需的。

    \n

    打开 Android Studio，下载 NDK 和 CMake：

    \n
    NDK (Side by side) 25.2.9519653
    CMake 4.0.2
    text
    \n
    2. \n
  2. \n

    设置环境变量：必须明确告诉构建脚本 Android SDK 和 NDK 在哪里。

    \n
    nano ~/.bashrc
    # 文件末尾添加 环境变量
    export ANDROID_SDK_ROOT=/home/vv/android/SDK
    export ANDROID_NDK_ROOT=/home/vv/android/SDK/ndk/25.2.9519653

    source ~/.bashrc
    bash
    \n

    注意：

    \n\n
    3. \n
\n

第二步：获取源码并执行编译​

\n
    \n
  1. \n

    克隆仓库：

    \n
    git clone https://github.com/arthenica/ffmpeg-kit.git
    cd ffmpeg-kit
    bash
    \n
    2. \n
  2. \n

    运行构建脚本：这是核心步骤。直接运行 android.sh 将开始为所有支持的架构（arm-v7a, arm64-v8a等）进行编译。

    \n
    # 强制 CMake 3.5 适配，仅当前窗口有效
    export CMAKE_POLICY_VERSION_MINIMUM=3.5

    ./android.sh --disable-arm-v7a --disable-arm-v7a-neon --disable-x86
    # 或者 
    ./android.sh --full --enable-gpl --disable-openssl --disable-arm-v7a --disable-arm-v7a-neon --disable-x86
    # --disable-openssl 和 --disable-lib-gnutls 二选一
    bash
    \n

    这个初次编译过程可能会非常耗时（可能需要半小时甚至更久，取决于电脑性能），因为它会从 GitHub 下载 FFmpeg 及其他几十个外部库的源码并逐个编译。

    \n

    如果是直接下载的 zip，需要修改 android.sh 脚本：

    \n
    # BUILD_VERSION=$(git describe --tags --always 2>>\"${BASEDIR}\"/build.log)
    BUILD_VERSION=\"6.0.2\"
    shell
    \n
    3. \n
  3. \n

    查看实时日志：打开一个新窗口，进入根目录下：

    \n
    tail -f build.log
    bash
    \n
    4. \n
\n

第三步：定制构建（可选）​

\n

这是自己编译的最大优势。可以通过添加参数来精确控制要编译哪些功能，从而有效控制最终 .aar 文件的大小。

\n\n

\"下载

\n

如果遇到类似报错：

\n
Please correct and use only one way to inject the SDK location.
  
  ANDROID_HOME: /home/vv/Android/Sdk
  ANDROID_SDK_ROOT: /home/vv/android/SDK
text
\n

解决方法：

\n
nano ~/.bashrc
# 只保留 ANDROID_SDK_ROOT，把 ANDROID_HOME 注释掉
source ~/.bashrc

./android.sh --full --enable-gpl --disable-openssl --disable-arm-v7a --disable-arm-v7a-neon --disable-x86
bash
\n

\"编译成功\"

\n

\"位置\"

\n

第四步：获取并使用生成的 .aar 文件​

\n
    \n
  1. \n

    找到 aar 文件：编译成功后，根据选择的构建类型，在以下路径找到生成的 .aar 文件：

    \n\n
    2. \n
  2. \n

    集成到项目：

    \n\n
    3. \n
\n
\n

总结​

\n
类别包含的库/功能作用说明
音频编解码lame
libilbc
libvorbis
opencore-amr
opus
shine
soxr
speex
twolame
vo-amrwbenc		MP3 编码
iLBC 语音编码
Vorbis 音频编码
AMR 语音编码
Opus 音频编解码
MP3 编码（固定点）
高质量重采样
Speex 语音编解码
MP2 音频编码
AMR-WB 语音编码
视频编解码（非GPL）dav1d
kvazaar
libtheora
libvpx		AV1 解码器
HEVC/H.265 编码器（非GPL）
Theora 视频编码
VP8/VP9 编解码
视频编解码（GPL）x264
x265
xvidcore		H.264/AVC 编码器
HEVC/H.265 编码器（GPL 版本）
MPEG-4 编码器
视频稳定vid.stab视频防抖滤镜（GPL）
字幕/字体/文字fontconfig
freetype
fribidi
libass		字体配置
字体渲染
双向文本布局
字幕渲染（ASS/SSA）
网络/加密gmp
gnutls
libxml2		加密数学库
HTTPS/TLS 支持
XML 解析
图像/像素处理libwebp
zimg
snappy		WebP 图像编解码
高保真图像缩放
快速压缩
字符集转换libiconv字符编码转换
Android 系统库zlib
MediaCodec		压缩/解压
硬件加速编解码
\n

重要说明​

\n", "url": "https://devvv.cn/blog/build-ffmpegkit-for-android", "title": "编译 ffmpegkit", "summary": "编译 ffmpegkit", "date_modified": "2026-03-31T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Android", "ffmpegkit" ] }, { "id": "https://devvv.cn/blog/local-deploy-ai-model-doc", "content_html": "

环境准备​

\n
名称详情
系统Win11 企业版 LTSC 64位 0103b OOBE
CPUi7 14700KF
内存64G
显卡RTX 5060T 16G
系统盘（C盘）至少 500 G
\n
注意

安装 Windows 系统必须选择 OOBE 模式

\n

安装 Ollama​

\n

下载地址：https://ollama.com/

\n

\"安装

\n

安装完成会有一个 UI 界面，直接关掉：

\n

\"Ollama

\n

打开 命令提示符 或 PowerShell，检查是否安装成功：

\n
ollama --version

ollama list
bash
\n

\"Ollama

\n

Ollama 安装路径为：

\n
C:\\Users\\weijun\\AppData\\Local\\Programs\\Ollama
text
\n

下载模型​

\n

编程模型：

\n
ollama pull deepseek-coder-v2:16b
bash
\n

\"deepseek

\n

模型不不保存路径：

\n
C:\\Users\\weijun\\.ollama\\models
text
\n

运行模型​

\n
ollama run deepseek-coder-v2:16b
bash
\n

启动后，会看到 >>> 提示符。输入一个问题，比如：“用 kotlin写一个快速排序”，然后回车。如果模型正常回复，说明部署成功。

\n

\"运行第一个模型\"

\n

退出模型​

\n

在 ollama run 的对话界面中，直接输入：

\n
/bye
bash
\n

然后按回车，即可退出模型会话，回到命令行提示符。模型会从显存中卸载。

\n

\"退出模型\"

\n

如果界面卡死，按 Ctrl + C 一次或多次，可以中断正在运行的进程。如果无效，可以关闭整个命令行窗口。

\n

或者打开另一个命令行窗口，运行：

\n
ollama stop deepseek-coder-v2:16b

ollama stop --all
bash
\n

安装 docker​

\n

下载并安装 Docker Desktop for Windows：https://www.docker.com/products/docker-desktop/。

\n

选择 Download for Windows – AMD64。

\n

安装完成后，重启 Windows 系统：

\n

\"重启Windows系统\"

\n

Windows 系统重启后，安装 WSL2：

\n

\"安装

\n

启动 Docker Desktop，在 Windows 系统托盘中看到它的鲸鱼图标为止。

\n

\"鲸鱼图标\"

\n

查看 Docker 总共占用了多少磁盘空间：

\n
docker system df
bash
\n

如果 C 盘空间紧张，可以在 Docker Desktop 的设置里，把存储位置改到其他容量更大的盘符。

\n

部署 Open WebUI​

\n

打开 命令提示符 (CMD) 或 PowerShell，执行：

\n
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
bash
\n

这个命令会自动从网上下载 Open WebUI 的镜像，并以后台服务的形式运行在 3000 端口上。

\n
\n

请注意：这条命令中 -v open-webui:/app/backend/data 这部分会将聊天记录和数据保存在 Docker 的存储卷中，即使容器更新或重启，数据也不会丢失

\n
\n

\"下载

\n

\"下载

\n

当 Docker 成功拉取并运行容器后（可能需要等待一两分钟），打开浏览器，访问地址：

\n
http://localhost:3000
text
\n

首次访问时，系统会提示注册一个账号（这是本地 WebUI 的管理员账号，信息只保存在自己的电脑里，非常安全）。注册完成后登录，就能看到之前在 Ollama 中下载好的所有模型了。

\n

在界面左上角的模型下拉菜单中，可以选择不同的模型进行对话、管理所有聊天记录。

\n

\"下载

\n

部署成功后，可以探索更多功能：

\n\n

常用命令​

\n
命令作用
ollama list列出已下载到本地的所有模型
ollama run <model>启动并进入模型对话界面
ollama stop <model>停止正在运行的指定模型
ollama stop --all停止所有正在运行的模型
ollama ps查看当前正在运行的模型列表
ollama pull <model>下载模型（如果已存在则更新）
ollama rm <model>删除本地模型
ollama cp <source> <dest>复制模型并创建别名
ollama serve以服务模式启动 Ollama（通常后台运行）
ollama --help查看全部命令帮助
\n
\n

提示：在 ollama run 对话中，除了 /bye 外，还可以使用 /help 查看其他内置命令（如 /clear 清空上下文）。

\n
\n

安装的模型记录​

\n
ollama pull deepseek-coder-v2:16b   # 10GB
ollama pull qwen3:14b   # 9GB
ollama pull qwen3:8b    # 5GB
bash
", "url": "https://devvv.cn/blog/local-deploy-ai-model-doc", "title": "本地部署 ai 模型", "summary": "本地部署 ai 模型", "date_modified": "2026-03-29T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "AI" ] }, { "id": "https://devvv.cn/blog/synology-web-station-add-second-site-setup", "content_html": "

创建共享文件夹​

\n

在群晖的 File Station 中，为第二个站点创建一个独立的文件夹（例如：/web_tools），并将所有文件上传至此：

\n

\"创建共享文件夹第一步\"

\n

\"创建共享文件夹第二步\"

\n

\"创建共享文件夹第三步\"

\n

\"创建共享文件夹第四步\"

\n

\"所有文件上传至此\"

\n

添加虚拟主机​

\n

打开 Web Station，进入 Web Station > 网络门户 或 虚拟主机，点击 新增，选择 网页门户服务：

\n

\"网页门户服务\"

\n

在 服务 项点击展开下拉列表，选择 新增服务：

\n\n

\"新增服务\"

\n

门户类型 选择 基于端口 的标签页下进行配置：

\n\n

\"基于端口\"

\n

然后进行局域网访问测试：

\n
http://192.168.3.7:8081
text
\n

添加映射​

\n

接下来，需要让花生壳将这个新的内网地址和端口映射到公网。

\n

先添加一个子域名，开启花生壳状态开关，解析模式切换为 内网穿透：

\n

\"子域名内网穿透\"

\n

在 内网穿透 页面，点击 添加映射：

\n

\"子域名内网穿透\"

\n

然后去 套间中心 先 停用 或 停止 花生壳，最后再 启动 即可正常访问。

\n
http://tool.devvv.cn
text
", "url": "https://devvv.cn/blog/synology-web-station-add-second-site-setup", "title": "群晖 Web Station 中部署第二个站点", "summary": "群晖 Web Station 中部署第二个站点", "date_modified": "2026-03-29T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "群晖" ] }, { "id": "https://devvv.cn/blog/mysql-ofential-commands-usage", "content_html": "

查看表结构​

\n
-- 查看表结构
DESC 表名;
-- 或
SHOW FULL COLUMNS FROM 表名;
sql
\n

删除表​

\n
-- 方法1：删除表结构和数据（最常用）
DROP TABLE 表名;

-- 方法2：删除前先检查表是否存在
DROP TABLE IF EXISTS 表名;

-- 方法3：清空表数据但保留表结构（如果需要保留表结构）
TRUNCATE TABLE 表名;
sql
\n

说明：

\n\n

请将 表名 替换为实际的表名。

", "url": "https://devvv.cn/blog/mysql-ofential-commands-usage", "title": "mysql 常用命令", "summary": "mysql 常用命令", "date_modified": "2026-03-27T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "MySQL" ] }, { "id": "https://devvv.cn/blog/docker-delete-container", "content_html": "

要清空所有 Docker 容器，可以使用以下命令：

\n

1. 删除所有已停止的容器​

\n
docker container prune
bash
\n

系统会提示确认，输入 y 即可删除所有已停止的容器。

\n

\"docker删除容器后\"

\n

2. 强制删除所有容器（包括运行中的）​

\n
docker rm -f $(docker ps -aq)
bash
\n

这个命令会：

\n\n

3. 更安全的方式 - 先停止再删除​

\n
# 停止所有运行中的容器
docker stop $(docker ps -q)

# 删除所有容器
docker rm $(docker ps -aq)
bash
\n

执行后的效果​

\n

根据你提供的列表，这些容器都会被删除：

\n\n
\n

建议：如果你还想清理未使用的镜像、卷等资源，可以执行：

\n
docker system prune -a
bash
\n

这个命令会清理所有未使用的容器、镜像、网络和构建缓存。

", "url": "https://devvv.cn/blog/docker-delete-container", "title": "docker 删除容器", "summary": "docker 删除容器", "date_modified": "2026-03-25T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "docker" ] }, { "id": "https://devvv.cn/blog/service-from-cpp-to-springboot-nice", "content_html": "

创建项目​

\n

\"SpringBoot新建项目第一步\"

\n

\"SpringBoot新建项目勾选依赖\"

\n

完整的 build.gradle.kts 文件如下：

\n
build.gradle.ktskotlin
plugins {
    kotlin(\"jvm\") version \"2.2.21\"
    kotlin(\"plugin.spring\") version \"2.2.21\"
    id(\"org.springframework.boot\") version \"4.0.4\"
    id(\"io.spring.dependency-management\") version \"1.1.7\"
    kotlin(\"plugin.jpa\") version \"2.2.21\"
}

group = \"com.vv\"
version = \"0.0.1-SNAPSHOT\"
description = \"FriendlyServerV2\"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation(\"org.springframework.boot:spring-boot-starter-data-jpa\")
    implementation(\"org.springframework.boot:spring-boot-starter-data-redis\")
    implementation(\"org.springframework.boot:spring-boot-starter-webmvc\")
    implementation(\"org.jetbrains.kotlin:kotlin-reflect\")
    implementation(\"tools.jackson.module:jackson-module-kotlin\")
    developmentOnly(\"org.springframework.boot:spring-boot-devtools\")
    runtimeOnly(\"com.mysql:mysql-connector-j\")
    testImplementation(\"org.springframework.boot:spring-boot-starter-data-jpa-test\")
    testImplementation(\"org.springframework.boot:spring-boot-starter-data-redis-test\")
    testImplementation(\"org.springframework.boot:spring-boot-starter-webmvc-test\")
    testImplementation(\"org.jetbrains.kotlin:kotlin-test-junit5\")
    testRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")

    implementation(\"org.springframework.boot:spring-boot-starter-security\")
    implementation(\"io.netty:netty-all:4.2.5.Final\")   // 包含所有 Netty 组件，也可按需拆分
    implementation(\"io.jsonwebtoken:jjwt-api:0.12.6\")
    runtimeOnly(\"io.jsonwebtoken:jjwt-impl:0.12.6\")
    runtimeOnly(\"io.jsonwebtoken:jjwt-jackson:0.12.6\")
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll(\"-Xjsr305=strict\", \"-Xannotation-default-target=param-property\")
    }
}

allOpen {
    annotation(\"jakarta.persistence.Entity\")
    annotation(\"jakarta.persistence.MappedSuperclass\")
    annotation(\"jakarta.persistence.Embeddable\")
}

tasks.withType<Test> {
    useJUnitPlatform()
}
\n

Docker 容器化​

\n
Dockerfile.devdockerfile
# 使用 Ubuntu 24.04 作为基础镜像
FROM ubuntu:24.04 AS dev

# 设置时区，避免交互式安装
ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=Asia/Shanghai

# 更新系统并安装必要工具：wget、unzip、curl（健康检查）、OpenJDK 17
RUN apt-get update && \\
    apt-get install -y --no-install-recommends \\
        wget \\
        unzip \\
        curl \\
        openjdk-17-jdk \\
        && \\
    rm -rf /var/lib/apt/lists/*

# 安装 Gradle 9.4.0
ENV GRADLE_VERSION=9.4.0
ENV GRADLE_HOME=/opt/gradle
RUN wget -q https://mirrors.cloud.tencent.com/gradle/gradle-${GRADLE_VERSION}-bin.zip -O /tmp/gradle.zip && \\
    unzip /tmp/gradle.zip -d /opt && \\
    rm /tmp/gradle.zip && \\
    mv /opt/gradle-${GRADLE_VERSION} ${GRADLE_HOME} && \\
    ln -s ${GRADLE_HOME}/bin/gradle /usr/local/bin/gradle

# 设置工作目录（与 docker-compose 中的卷挂载路径一致）
WORKDIR /workspace

# 暴露端口（HTTP 端口 8080，自定义 Netty 端口 8081）
EXPOSE 8080 8081

# 使用 gradle bootRun 启动，开启 Spring Boot DevTools 热重启
# 添加 --no-daemon 避免守护进程残留
CMD [\"./gradlew\", \"bootRun\", \"--no-daemon\"]
\n

相关命令：

\n
# 每次修改代码后，先停止服务再启动
docker stop dev
docker compose --profile dev up -d
docker compose --profile dev up
# 日志查看
docker compose logs -f dev
# 重新构建（代码修改后）
docker compose --profile dev up -d --build
bash
\n

新增测试接口：

\n
TestController.ktkotlin
package com.vv.friendlyserverv2.controller

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class TestController {

    @GetMapping(\"/test\")
    fun test(): Map<String, String> = mapOf(\"message\" to \"Hello from FriendlyServer\")
}
\n

如果端口被占用：

\n
# 查看占用的进程
sudo lsof -i :6379
# 停止本地Redis进程
sudo systemctl stop redis-server
# 禁止开机自启
sudo systemctl disable redis-server
sudo systemctl disable mysql
# 重启开发环境
docker compose --profile dev up -d
bash
\n

多等一会儿，就能成功启动了。

\n

然后访问 http://localhost:8080/test 测试接口。

\n

开发环境下，大部分代码变更不需要重启 Docker 容器，因为：

\n
    \n
  1. 卷挂载：- .:/workspace 将宿主机源码目录同步到容器内。
    2. \n
  2. 热重载：Spring Boot DevTools 已启用（日志中出现 Devtools property defaults active），它会监听类路径变化，自动重启应用上下文。
    3. \n
  3. Gradle 持续运行：./gradlew bootRun 会检测源码变化并重新编译、重新加载。
    4. \n
\n

少数情况需要重启容器：

\n\n

建议做法：

\n\n

生产环境：代码变更必须重新构建镜像并重启容器。

\n

mysql 初始化​

\n

将 init.sql 放到 src/main/resources/db/init.sql（如果目录不存在则创建）：

\n
init.sqlsql
-- 用户基本信息表( KEY idx_username (username)  -- 添加索引提升登录查询速度)
CREATE TABLE IF NOT EXISTS platform_user
(
    id            INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户唯一ID',
    username      VARCHAR(50) UNIQUE NOT NULL COMMENT '用户名，用于登录和显示',
    password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希值',
    nickname      VARCHAR(50) DEFAULT NULL COMMENT '用户昵称',
    avatar_url    VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
    email         VARCHAR(255) DEFAULT NULL COMMENT '绑定的邮箱',
    phone         VARCHAR(50) DEFAULT NULL COMMENT '绑定的手机号',
    bio           TEXT COMMENT '个人简介',
    last_login_at DATETIME NULL DEFAULT NULL COMMENT '最后登录时间',
    created_at    DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at    DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    is_deleted    TINYINT(1) DEFAULT 0 COMMENT '软删除标记(0:正常 1:删除)',
    KEY idx_username (username),
    KEY idx_is_deleted (is_deleted),
    KEY idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户基本信息表';

-- 平台信息表
CREATE TABLE IF NOT EXISTS platform_info
(
    id            INT PRIMARY KEY AUTO_INCREMENT COMMENT '平台ID',
    name          VARCHAR(100) UNIQUE NOT NULL COMMENT '平台名称/标识，例如：码云、QQ、GitHub',
    url           VARCHAR(255) DEFAULT NULL COMMENT '平台网址',
    icon_url      VARCHAR(255) DEFAULT NULL COMMENT '平台图标URL，可选',
    description   VARCHAR(255) DEFAULT NULL COMMENT '平台描述',
    owner_user_id INT NOT NULL COMMENT '所属用户ID，关联platform_user表',
    created_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (owner_user_id) REFERENCES platform_user(id) ON DELETE RESTRICT ON UPDATE CASCADE,
    KEY idx_owner_user_id (owner_user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='平台信息表';

-- 账号密码表（关联平台）
-- UNIQUE KEY uk_user_platform_account (owner_user_id, platform_id, account_name): 防止同一用户在同一平台重复添加同一个账号
CREATE TABLE IF NOT EXISTS platform_account
(
    id            INT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
    platform_id   INT NOT NULL COMMENT '平台ID，关联platform_info表',
    account_name  VARCHAR(100) NOT NULL COMMENT '登录账号/用户名',
    password_hash VARCHAR(255) NOT NULL COMMENT '密码（加密存储）',
    bound_email   VARCHAR(255) DEFAULT NULL COMMENT '绑定的邮箱',
    bound_phone   VARCHAR(50) DEFAULT NULL COMMENT '绑定的手机号',
    owner_user_id INT NOT NULL COMMENT '所属用户ID，关联platform_user表',
    remark        TEXT COMMENT '备注信息',
    created_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (platform_id) REFERENCES platform_info(id) ON DELETE CASCADE ON UPDATE CASCADE,
    FOREIGN KEY (owner_user_id) REFERENCES platform_user(id) ON DELETE RESTRICT ON UPDATE CASCADE,
    UNIQUE KEY uk_user_platform_account (owner_user_id, platform_id, account_name),
    KEY idx_platform_id (platform_id),
    KEY idx_account_name (account_name),
    KEY idx_bound_email (bound_email),
    KEY idx_bound_phone (bound_phone),
    KEY idx_owner_user_id (owner_user_id),
    KEY idx_user_platform (owner_user_id, platform_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='平台账号表（含绑定信息）';

-- 插入用户
-- INSERT INTO platforms_users (username, password_hash, nickname)
-- VALUES ('zhangsan', 'hashed_password_here', '张三');
-- -- 插入平台
-- INSERT INTO platforms_info (name, url)
-- VALUES ('码云', 'https://gitee.com'), ('GitHub', 'https://github.com');
-- -- 插入账号密码记录（owner_user_id 用 INT 类型）
-- INSERT INTO platforms_account_passwords
-- (platform_id, account_name, password_hash, owner_user_id, bound_email, bound_phone)
-- VALUES(1, 'zhangsan_gitee', 'pwd_hash', 1, 'zhang@email.com', '13800138000');

-- web 站点首页埋点
CREATE TABLE IF NOT EXISTS web_page_track_home
(
    id                BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '访问记录唯一ID',
    visit_timestamp   BIGINT NOT NULL COMMENT '访问时间戳(毫秒)',
    visit_date        DATETIME GENERATED ALWAYS AS (FROM_UNIXTIME(visit_timestamp/1000)) STORED COMMENT '访问日期(方便查询)',
    url               VARCHAR(500) NOT NULL COMMENT '访问的完整URL',
    referrer          VARCHAR(500) DEFAULT NULL COMMENT '来源页面',
    referrer_domain   VARCHAR(255) GENERATED ALWAYS AS (SUBSTRING_INDEX(SUBSTRING_INDEX(referrer, '/', 3), '://', -1)) STORED COMMENT '来源域名',
    user_agent        TEXT COMMENT '用户浏览器信息',
    browser           VARCHAR(50) GENERATED ALWAYS AS (
                        CASE
                            WHEN user_agent LIKE '%Chrome%' AND user_agent NOT LIKE '%Edg%' THEN 'Chrome'
                            WHEN user_agent LIKE '%Edg%' THEN 'Edge'
                            WHEN user_agent LIKE '%Firefox%' THEN 'Firefox'
                            WHEN user_agent LIKE '%Safari%' AND user_agent NOT LIKE '%Chrome%' THEN 'Safari'
                            ELSE 'Other'
                            END
                      ) STORED COMMENT '浏览器类型',
    os                VARCHAR(50) GENERATED ALWAYS AS (
                        CASE
                            WHEN user_agent LIKE '%Windows%' THEN 'Windows'
                            WHEN user_agent LIKE '%Mac OS%' THEN 'macOS'
                            WHEN user_agent LIKE '%Linux%' THEN 'Linux'
                            WHEN user_agent LIKE '%Android%' THEN 'Android'
                            WHEN user_agent LIKE '%iPhone%' OR user_agent LIKE '%iPad%' THEN 'iOS'
                            ELSE 'Other'
                            END
                      ) STORED COMMENT '操作系统',
    device_type       VARCHAR(20) GENERATED ALWAYS AS (
                        CASE
                            WHEN user_agent LIKE '%Mobile%' THEN 'Mobile'
                            WHEN user_agent LIKE '%Tablet%' THEN 'Tablet'
                            ELSE 'Desktop'
                            END
                      ) STORED COMMENT '设备类型',
    language          VARCHAR(20) DEFAULT NULL COMMENT '浏览器语言',
    screen_resolution VARCHAR(20) DEFAULT NULL COMMENT '屏幕分辨率',
    ip_address        VARCHAR(45) DEFAULT NULL COMMENT '访问者IP地址',
    created_at        DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '记录创建时间',

    KEY idx_visit_date (visit_date),
    KEY idx_referrer_domain (referrer_domain),
    KEY idx_browser (browser),
    KEY idx_os (os),
    KEY idx_device_type (device_type),
    KEY idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='web首页访问统计表';
\n

由于容器已存在数据卷 mysql_data，首次启动后数据库已初始化，再次启动不会重新执行脚本。因此需要删除现有数据卷，让 MySQL 重新初始化：

\n
docker compose --profile dev down -v   # 删除容器和数据卷
docker compose --profile dev up -d     # 重新启动，此时会执行 init.sql
bash
\n

完成后，MySQL 会按 init.sql 建表。

\n

执行以下命令进入 MySQL 容器并查看表：

\n
docker exec -it friendly-mysql mysql -uroot -proot
bash
\n

进入 MySQL 后，执行：

\n
SHOW databases;
USE db_friendly;
SHOW TABLES;
sql
\n

如果看到 platform_user、platform_info、platform_account、web_page_track_home 四张表，则表示建表成功。

\n

退出 MySQL：输入 exit 或按 Ctrl+D。

\n

\"验证Mysql表是否初始化成功\"

\n

创建 JPA 实体类​

\n

在项目根目录下创建以下路径和文件：

\n
src/main/kotlin/com/vv/friendlyserverv2/entity/
├── PlatformUser.kt
├── PlatformInfo.kt
├── PlatformAccount.kt
└── WebPageTrackHome.kt
text
\n
PlatformUser.ktkotlin
package com.vv.friendlyserverv2.entity

import jakarta.persistence.*
import org.hibernate.annotations.CreationTimestamp
import org.hibernate.annotations.UpdateTimestamp
import java.time.LocalDateTime

@Entity
@Table(name = \"platform_user\")
data class PlatformUser(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Int = 0,

    @Column(unique = true, nullable = false, length = 50)
    var username: String,

    @Column(name = \"password_hash\", nullable = false, length = 255)
    var passwordHash: String,

    @Column(length = 50)
    var nickname: String? = null,

    @Column(name = \"avatar_url\", length = 255)
    var avatarUrl: String? = null,

    @Column(length = 255)
    var email: String? = null,

    @Column(length = 50)
    var phone: String? = null,

    @Column(columnDefinition = \"TEXT\")
    var bio: String? = null,

    @Column(name = \"last_login_at\")
    var lastLoginAt: LocalDateTime? = null,

    @CreationTimestamp
    @Column(name = \"created_at\", updatable = false)
    var createdAt: LocalDateTime = LocalDateTime.now(),

    @UpdateTimestamp
    @Column(name = \"updated_at\")
    var updatedAt: LocalDateTime = LocalDateTime.now(),

    @Column(name = \"is_deleted\")
    var isDeleted: Boolean = false
)
\n
\n

创建完成后，运行以下命令确认实体类能被 JPA 扫描到：

\n
docker compose --profile dev restart dev
bash
\n

查看日志，没报错就行：

\n
docker compose logs -f dev
bash
\n

创建 Repository​

\n

在项目根目录下创建以下路径和文件：

\n
src/main/kotlin/com/vv/friendlyserverv2/repository/
├── PlatformUserRepository.kt
├── PlatformInfoRepository.kt
├── PlatformAccountRepository.kt
└── WebPageTrackHomeRepository.kt
text
\n
PlatformUserRepository.ktkotlin
package com.vv.friendlyserverv2.repository

import com.vv.friendlyserverv2.entity.PlatformUser
import org.springframework.data.jpa.repository.JpaRepository
import org.springframework.data.jpa.repository.Modifying
import org.springframework.data.jpa.repository.Query
import org.springframework.data.repository.query.Param
import org.springframework.stereotype.Repository
import java.util.*

@Repository
interface PlatformUserRepository : JpaRepository<PlatformUser, Int> {

    /**
     * 根据用户名查询未删除的用户
     */
    fun findByUsernameAndIsDeletedFalse(username: String): Optional<PlatformUser>

    /**
     * 根据用户ID查询未删除的用户
     */
    fun findByIdAndIsDeletedFalse(id: Int): Optional<PlatformUser>

    /**
     * 检查用户名是否已存在（排除已删除的用户）
     */
    fun existsByUsernameAndIsDeletedFalse(username: String): Boolean

    /**
     * 更新最后登录时间
     */
    @Modifying
    @Query(\"UPDATE PlatformUser u SET u.lastLoginAt = CURRENT_TIMESTAMP WHERE u.id = :userId AND u.isDeleted = false\")
    fun updateLastLoginTime(@Param(\"userId\") userId: Int): Int
}
\n

创建完成后，重启开发环境验证：

\n
docker compose --profile dev restart dev
bash
\n

查看日志，没报错就行：

\n
docker compose logs -f dev
bash
\n

创建 DTO 类​

\n

在项目根目录下创建以下路径和文件：

\n
src/main/kotlin/com/vv/friendlyserverv2/dto/
├── ApiResponse.kt
├── LoginResponse.kt
├── RefreshTokenResponse.kt
├── RegisterResponse.kt
├── UserInfoResponse.kt
├── UserUpdateRequest.kt
├── AccountQueryResponse.kt
├── AccountAddRequest.kt
├── AccountDeleteRequest.kt
├── PlatformQueryResponse.kt
├── PlatformAddRequest.kt
├── PlatformDeleteRequest.kt
├── PlatformBatchDeleteRequest.kt
└── HomeTrackRequest.kt
text
\n
ApiResponse.ktkotlin
package com.vv.friendlyserverv2.dto

import com.fasterxml.jackson.annotation.JsonInclude
import java.time.Instant

/**
 * 统一 API 响应格式
 * 参考旧 C++ 项目 HttpResponse::ResponseModel
 */
@JsonInclude(JsonInclude.Include.NON_NULL)
data class ApiResponse<T>(
    val code: Int,           // 业务状态码，0 表示成功
    val message: String,     // 响应消息
    val data: T?,            // 响应数据（可选）
    val timestamp: Long = Instant.now().toEpochMilli()  // 时间戳
) {

    companion object {
        // 成功响应（带数据）
        fun <T> success(data: T, message: String = \"请求成功\"): ApiResponse<T> {
            return ApiResponse(0, message, data)
        }

        // 成功响应（无数据）
        fun success(message: String = \"请求成功\"): ApiResponse<Unit> {
            return ApiResponse(0, message, null)
        }

        // 错误响应
        fun error(code: Int, message: String): ApiResponse<Unit> {
            return ApiResponse(code, message, null)
        }

        // 400 错误
        fun badRequest(message: String = \"请求参数错误\"): ApiResponse<Unit> {
            return ApiResponse(400, message, null)
        }

        // 401 未授权
        fun unauthorized(message: String = \"未授权访问\"): ApiResponse<Unit> {
            return ApiResponse(401, message, null)
        }

        // 403 禁止访问
        fun forbidden(message: String = \"禁止访问\"): ApiResponse<Unit> {
            return ApiResponse(403, message, null)
        }

        // 404 资源不存在
        fun notFound(message: String = \"资源不存在\"): ApiResponse<Unit> {
            return ApiResponse(404, message, null)
        }

        // 500 服务器内部错误
        fun internalError(message: String = \"服务器内部错误\"): ApiResponse<Unit> {
            return ApiResponse(500, message, null)
        }
    }
}
\n

创建 Service 层（业务逻辑）​

\n
src/main/kotlin/com/vv/friendlyserverv2/
├── config/
│   └── SecurityConfig.kt
└── service/
    ├── BaseService.kt
    ├── JwtService.kt
    ├── PlatformUserService.kt
    ├── PlatformInfoService.kt
    ├── PlatformAccountService.kt
    └── WebTrackService.kt
text
\n

添加 Spring Security 依赖，在 build.gradle.kts 的 dependencies 块中添加：

\n
build.gradle.ktskts
implementation(\"org.springframework.boot:spring-boot-starter-security\")
\n
备注

注意：添加 Spring Security 后，默认会启用安全过滤器链，所有接口都需要认证。我们需要禁用它（因为我们自己实现 JWT 认证）。

\n

在 SecurityConfig.kt 中添加配置：

\n
SecurityConfig.ktkotlin
package com.vv.friendlyserverv2.config

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.web.SecurityFilterChain

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    fun passwordEncoder(): PasswordEncoder {
        return BCryptPasswordEncoder()
    }

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http
            .csrf { it.disable() }
            .authorizeHttpRequests { auth ->
                auth.anyRequest().permitAll()  // 允许所有请求，由我们自己处理认证
            }
            .sessionManagement { session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            }
        return http.build()
    }
}
\n
BaseService.ktkotlin
package com.vv.friendlyserverv2.service

import com.vv.friendlyserverv2.dto.ApiResponse

/**
 * Service 层基类，提供通用的验证、转换方法
 */
abstract class BaseService {

    // ============ 参数验证方法 ============

    /**
     * 验证字符串不为空
     */
    protected fun requireNotBlank(value: String?, fieldName: String) {
        if (value.isNullOrBlank()) {
            throw IllegalArgumentException(\"$fieldName 不能为空\")
        }
    }

    /**
     * 验证字符串长度范围
     */
    protected fun validateLength(value: String?, fieldName: String, min: Int = 0, max: Int = Int.MAX_VALUE) {
        if (value != null) {
            if (value.length < min) {
                throw IllegalArgumentException(\"$fieldName 长度不能小于 $min\")
            }
            if (value.length > max) {
                throw IllegalArgumentException(\"$fieldName 长度不能超过 $max\")
            }
        }
    }

    /**
     * 验证字符串非空且长度范围
     */
    protected fun validateRequiredLength(value: String, fieldName: String, min: Int = 1, max: Int = Int.MAX_VALUE) {
        requireNotBlank(value, fieldName)
        validateLength(value, fieldName, min, max)
    }

    /**
     * 验证 ID 大于 0
     */
    protected fun validateId(id: Int, fieldName: String = \"ID\") {
        if (id <= 0) {
            throw IllegalArgumentException(\"$fieldName 不正确\")
        }
    }

    /**
     * 验证 ID 列表不为空且所有 ID 大于 0
     */
    protected fun validateIds(ids: List<Int>, fieldName: String = \"ID列表\") {
        if (ids.isEmpty()) {
            throw IllegalArgumentException(\"$fieldName 不能为空\")
        }
        ids.forEach { validateId(it, fieldName) }
    }

    /**
     * 验证邮箱格式
     */
    protected fun validateEmail(email: String?) {
        email?.let {
            if (it.length > 100) {
                throw IllegalArgumentException(\"邮箱地址不能超过 100 个字符\")
            }
            // 简单邮箱格式验证
            val emailRegex = Regex(\"^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\\\\.[A-Za-z]{2,}$\")
            if (!emailRegex.matches(it)) {
                throw IllegalArgumentException(\"邮箱格式不正确\")
            }
        }
    }

    /**
     * 验证手机号格式（11 位数字）
     */
    protected fun validatePhone(phone: String?) {
        phone?.let {
            if (it.length != 11 || !it.all { char -> char.isDigit() }) {
                throw IllegalArgumentException(\"手机号只能为 11 个数字\")
            }
        }
    }

    /**
     * 验证用户名格式（6-20 位字母或数字）
     */
    protected fun validateUsername(username: String) {
        validateRequiredLength(username, \"用户名\", 6, 20)
        val usernameRegex = Regex(\"^[A-Za-z0-9]+$\")
        if (!usernameRegex.matches(username)) {
            throw IllegalArgumentException(\"用户名只能包含英文和数字\")
        }
    }

    /**
     * 验证密码格式（6-20 位字母或数字）
     */
    protected fun validatePassword(password: String) {
        validateRequiredLength(password, \"密码\", 6, 20)
        val passwordRegex = Regex(\"^[A-Za-z0-9]+$\")
        if (!passwordRegex.matches(password)) {
            throw IllegalArgumentException(\"密码只能包含英文和数字\")
        }
    }

    /**
     * 验证昵称（最大 50 字符）
     */
    protected fun validateNickname(nickname: String?) {
        validateLength(nickname, \"昵称\", max = 50)
    }

    /**
     * 验证平台名称
     */
    protected fun validatePlatformName(name: String) {
        validateRequiredLength(name, \"平台名\", 1, 50)
    }

    /**
     * 验证 URL 长度
     */
    protected fun validateUrl(url: String?, fieldName: String = \"URL\", max: Int = 255) {
        validateLength(url, fieldName, max = max)
    }

    /**
     * 验证描述长度
     */
    protected fun validateDescription(description: String?, max: Int = 255) {
        validateLength(description, \"描述\", max = max)
    }

    /**
     * 验证账号名
     */
    protected fun validateAccountName(name: String) {
        validateRequiredLength(name, \"账号名\", 1, 50)
    }

    /**
     * 验证账号密码
     */
    protected fun validateAccountPassword(password: String) {
        validateRequiredLength(password, \"账号密码\", 1, 50)
    }

    /**
     * 验证备注长度
     */
    protected fun validateRemark(remark: String?, max: Int = 255) {
        validateLength(remark, \"备注\", max = max)
    }

    /**
     * 验证个人简介长度
     */
    protected fun validateBio(bio: String?, max: Int = 500) {
        validateLength(bio, \"个人简介\", max = max)
    }

    // ============ 成功/错误响应构建方法 ============

    /**
     * 构建成功响应（带数据）
     */
    protected fun <T> success(data: T, message: String = \"请求成功\"): ApiResponse<T> {
        return ApiResponse.success(data, message)
    }

    /**
     * 构建成功响应（无数据）
     */
    protected fun success(message: String = \"请求成功\"): ApiResponse<Unit> {
        return ApiResponse.success(message)
    }

    /**
     * 构建错误响应
     */
    protected fun error(code: Int = 400, message: String): ApiResponse<Unit> {
        return ApiResponse.error(code, message)
    }

    /**
     * 构建 400 错误响应
     */
    protected fun badRequest(message: String = \"请求参数错误\"): ApiResponse<Unit> {
        return ApiResponse.badRequest(message)
    }

    /**
     * 构建 401 错误响应
     */
    protected fun unauthorized(message: String = \"未授权访问\"): ApiResponse<Unit> {
        return ApiResponse.unauthorized(message)
    }

    /**
     * 构建 403 错误响应
     */
    protected fun forbidden(message: String = \"禁止访问\"): ApiResponse<Unit> {
        return ApiResponse.forbidden(message)
    }

    /**
     * 构建 404 错误响应
     */
    protected fun notFound(message: String = \"资源不存在\"): ApiResponse<Unit> {
        return ApiResponse.notFound(message)
    }

    /**
     * 构建 500 错误响应
     */
    protected fun internalError(message: String = \"服务器内部错误\"): ApiResponse<Unit> {
        return ApiResponse.internalError(message)
    }
}
\n

创建 Controller 层​

\n
src/main/kotlin/com/vv/friendlyserverv2/
├── controller/
│   ├── BaseController.kt
│   ├── AuthController.kt
│   ├── UserController.kt
│   ├── AccountController.kt
│   ├── PlatformController.kt
│   ├── TrackController.kt
│   └── HealthController.kt
text
\n
BaseController.ktkotlin
package com.vv.friendlyserverv2.controller

import com.vv.friendlyserverv2.dto.ApiResponse
import com.vv.friendlyserverv2.service.JwtService
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ExceptionHandler

/**
 * Controller 层基类，提供通用的 Token 提取和响应构建方法
 */
abstract class BaseController {

    @Autowired
    protected lateinit var jwtService: JwtService

    // ============ Token 提取方法 ============

    /**
     * 从 Authorization Header 提取 Token
     */
    protected fun extractToken(authHeader: String?): String? {
        if (authHeader.isNullOrBlank()) return null
        return authHeader.removePrefix(\"Bearer \").trim()
    }

    /**
     * 验证 Token 并提取用户 ID
     */
    protected fun getUserIdFromToken(authHeader: String?): Int? {
        val token = extractToken(authHeader) ?: return null
        return if (jwtService.verifyToken(token)) {
            jwtService.extractUserId(token)
        } else null
    }

    /**
     * 验证 Token 并提取用户信息
     */
    protected fun validateTokenAndGetUserId(authHeader: String?): Int {
        val userId = getUserIdFromToken(authHeader)
            ?: throw IllegalArgumentException(\"未授权访问\")
        return userId
    }

    // ============ 成功响应构建方法 ============

    /**
     * 构建成功响应（带数据）
     */
    protected fun <T> success(data: T, message: String = \"请求成功\"): ResponseEntity<ApiResponse<T>> {
        return ResponseEntity.ok(ApiResponse.success(data, message))
    }

    /**
     * 构建成功响应（无数据）
     */
    protected fun success(message: String = \"请求成功\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.ok(ApiResponse.success(message))
    }

    /**
     * 构建成功响应（自定义状态码）
     */
    protected fun <T> success(data: T, status: HttpStatus, message: String = \"请求成功\"): ResponseEntity<ApiResponse<T>> {
        return ResponseEntity.status(status).body(ApiResponse.success(data, message))
    }

    // ============ 错误响应构建方法 ============

    /**
     * 构建错误响应
     */
    protected fun <T> error(code: Int, message: String): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.badRequest().body(ApiResponse.error(code, message))
    }

    /**
     * 构建 400 错误响应
     */
    protected fun badRequest(message: String = \"请求参数错误\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.badRequest().body(ApiResponse.badRequest(message))
    }

    /**
     * 构建 401 错误响应
     */
    protected fun unauthorized(message: String = \"未授权访问\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(ApiResponse.unauthorized(message))
    }

    /**
     * 构建 403 错误响应
     */
    protected fun forbidden(message: String = \"禁止访问\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiResponse.forbidden(message))
    }

    /**
     * 构建 404 错误响应
     */
    protected fun notFound(message: String = \"资源不存在\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ApiResponse.notFound(message))
    }

    /**
     * 构建 500 错误响应
     */
    protected fun internalError(message: String = \"服务器内部错误\"): ResponseEntity<ApiResponse<Unit>> {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(ApiResponse.internalError(message))
    }

    // ============ 全局异常处理 ============

    /**
     * 处理 IllegalArgumentException（业务异常）
     */
    @ExceptionHandler(IllegalArgumentException::class)
    protected fun handleIllegalArgumentException(e: IllegalArgumentException): ResponseEntity<ApiResponse<Unit>> {
        return badRequest(e.message ?: \"请求参数错误\")
    }

    /**
     * 处理 Exception（系统异常）
     */
    @ExceptionHandler(Exception::class)
    protected fun handleException(e: Exception): ResponseEntity<ApiResponse<Unit>> {
        e.printStackTrace()
        return internalError(e.message ?: \"服务器内部错误\")
    }
}
\n

配置 application.yml​

\n

创建 src/main/resources/application.yml 文件，内容如下：

\n
application.ymlyaml
# Spring Boot 基础配置
spring:
  application:
    name: FriendlyServerV2
  
  # 数据源配置（MySQL）
  datasource:
    url: ${SPRING_DATASOURCE_URL:jdbc:mysql://mysql:3306/db_friendly?useSSL=false&serverTimezone=UTC&characterEncoding=utf8&allowPublicKeyRetrieval=true}
    username: ${SPRING_DATASOURCE_USERNAME:vv}
    password: ${SPRING_DATASOURCE_PASSWORD:vvpwd123}
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      idle-timeout: 30000
      connection-timeout: 30000
      max-lifetime: 1800000
  
  # JPA 配置
  jpa:
    hibernate:
      ddl-auto: validate  # 验证表结构，不自动创建（使用 init.sql 建表）
    show-sql: false       # 开发环境可设为 true 查看 SQL
    properties:
      hibernate:
#        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true
        jdbc:
          batch_size: 20
        order_inserts: true
        order_updates: true
  
  # Redis 配置
  data:
    redis:
      host: ${SPRING_DATA_REDIS_HOST:redis}
      port: ${SPRING_DATA_REDIS_PORT:6379}
      password: ${SPRING_DATA_REDIS_PASSWORD:}
      timeout: 5000ms
      lettuce:
        pool:
          max-active: 8
          max-idle: 8
          min-idle: 0
          max-wait: -1ms
  
  # Jackson 配置（JSON 序列化）
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Shanghai
    deserialization:
      fail-on-unknown-properties: false

# 服务器配置
server:
  port: ${SERVER_PORT:8080}
  servlet:
    context-path: /
    encoding:
      charset: UTF-8
      enabled: true
      force: true
  compression:
    enabled: true
    mime-types: application/json,application/xml,text/html,text/plain

# JWT 配置
jwt:
  secret: ${JWT_SECRET:lIXQJyQznJ+rQ0eafwSAD5tXqaKKJWh5VfZErNDUcSs}
  expiration: ${JWT_EXPIRATION:604800000}  # 7天 = 7 * 24 * 3600 * 1000 = 604800000 毫秒

# 日志配置
logging:
  level:
    root: INFO
    com.vv.friendlyserverv2: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: WARN
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
  pattern:
    console: \"%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n\"
    file: \"%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n\"
  file:
    name: logs/friendlyserver.log
    max-size: 10MB
    max-history: 7

# 管理端点配置（可选，用于监控）
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
      base-path: /actuator
  endpoint:
    health:
      show-details: always

# 应用自定义配置
app:
  # 跨域配置
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000,http://localhost:8080}
    allowed-methods: GET,POST,PUT,DELETE,OPTIONS
    allowed-headers: \"*\"
    allow-credentials: true
    max-age: 3600
\n

配置文件说明：

\n
    \n
  1. 环境变量覆盖\n配置中使用 ${VAR:default} 格式，可以通过环境变量覆盖默认值：
    2. \n
\n
环境变量说明默认值
SPRING_DATASOURCE_URLMySQL 连接地址jdbc:mysql://mysql:3306/db_friendly?...
SPRING_DATASOURCE_USERNAMEMySQL 用户名vv
SPRING_DATASOURCE_PASSWORDMySQL 密码vvpwd123
SPRING_DATA_REDIS_HOSTRedis 主机redis
SPRING_DATA_REDIS_PORTRedis 端口6379
SERVER_PORT服务端口8080
JWT_SECRETJWT 密钥默认开发密钥（生产必须修改）
JWT_EXPIRATIONJWT 过期时间（毫秒）3600000（1小时）
\n
    \n
  1. JPA 配置说明
    2. \n
\n\n
    \n
  1. 日志配置
    2. \n
\n\n
\n

验证配置文件

\n

创建完成后，停止容器服务并重新启动验证：

\n
docker stop dev
docker compose --profile dev up -d
# 日志查看
docker compose logs -f dev
bash
\n

访问：

\n

http://localhost:8080/api/test

\n

http://localhost:8080/api/health

\n

\"FriendlyServerV2迁移测试成功\"

\n

到这里全部迁移完成。

\n

MySQL 容器数据导入导出​

\n

导入数据​

\n

sql 数据位置：/home/vv/桌面/vv/idea/work/FriendlyServerV2/src/test/resources/db/insert.sql

\n

方法一：通过文件导入

\n
# 将 insert.sql 文件复制到容器内
docker cp /home/vv/桌面/vv/idea/work/FriendlyServerV2/src/test/resources/db/insert.sql friendly-mysql:/tmp/insert.sql

# 进入容器并执行
docker exec -it friendly-mysql bash
mysql -uroot -proot db_friendly < /tmp/insert.sql
bash
\n

方法二：直接执行（如果 insert.sql 在宿主机）

\n
docker exec -i friendly-mysql mysql -uroot -proot db_friendly < /path/insert.sql
bash
\n

导出数据​

\n

方法一：导出整个数据库

\n
docker exec friendly-mysql mysqldump -uroot -proot db_friendly > backup.sql
bash
\n

方法二：导出指定表

\n
docker exec friendly-mysql mysqldump -uroot -proot db_friendly platform_user > user_backup.sql
bash
\n

方法三：导出数据（不包含建表语句）

\n
docker exec friendly-mysql mysqldump -uroot -proot --no-create-info db_friendly > data_only.sql
bash
\n

直接在容器内操作​

\n
# 进入 MySQL 命令行
docker exec -it friendly-mysql mysql -uroot -proot db_friendly

# 在 MySQL 中执行批量插入
mysql> INSERT INTO platform_user (username, password_hash) VALUES ('test', 'hash');
mysql> source /tmp/insert.sql;  # 执行文件
bash
\n

常用导出选项​

\n
参数说明
--no-create-info不导出建表语句
--no-data只导出表结构
--where=\"id<100\"条件导出
--single-transaction保证一致性（InnoDB）
\n
\n

导出后，backup.sql 文件会保存在当前执行命令的目录下。

", "url": "https://devvv.cn/blog/service-from-cpp-to-springboot-nice", "title": "后端服务从 C++ 迁移到 SpringBoot", "summary": "后端服务从 C++ 迁移到 SpringBoot", "date_modified": "2026-03-24T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "SpringBoot", "Netty", "Kotlin", "MySQL", "Redis" ] }, { "id": "https://devvv.cn/blog/network-vpn-and-internet-tunneling-principles", "content_html": "

为什么会有这两个概念？​

\n

互联网的核心是设备之间相互发送数据包，每个设备需要唯一的 IP 地址。由于 IPv4 地址短缺，NAT（网络地址转换） 技术被广泛应用：你家路由器有一个公网 IP，而家里所有设备使用私有 IP（如 192.168.1.x）。
\nNAT 带来的限制是：内网设备可以主动访问外网，但外网很难主动访问内网设备。
\n为了解决这个问题，出现了两种技术：VPN 和内网穿透。它们的目标和实现方式完全不同。

\n
\n

1. 先从互联网的本质说起​

\n

互联网的本质是无数台设备（电脑、手机、服务器）之间相互发送数据包。
\n要让数据包正确送达，每台设备都需要一个唯一的地址，也就是 IP 地址。
\n在 IPv4 时代，地址不够用，所以有了 NAT（网络地址转换） 技术。
\n简单说，你家路由器有一个公网 IP（全球唯一），而你家所有设备（电脑、手机、电视）用的是私有 IP（如 192.168.1.x）。
\n当你家的电脑访问外网时，路由器会把数据包的源 IP 换成自己的公网 IP，并记住这个映射关系；收到回复时，再转换回私有 IP 发给你的电脑。

\n

关键点：

\n\n

这个限制就是 NAT 的“墙”：内网设备可以主动访问外网，但外网很难主动访问内网设备。

\n
\n

2. VPN 的本质和工作原理​

\n

2.1 本质​

\n

VPN（虚拟专用网络）是在公共网络上模拟出一个私有的、加密的、逻辑上的“局域网”。

\n

它不是在物理上改变网络，而是通过软件，让你的设备与另一个网络之间建立一条加密隧道。

\n

目标：让远程设备融入目标内网，获得一个内网 IP，从而像本地设备一样访问内网中的所有资源（不仅限于某个应用）。

\n

2.2 原理（以最常见的远程访问 VPN 为例）​

\n

2.2.1 场景设定​

\n\n

现在，你想在家访问公司内网的文件服务器 192.168.10.5。

\n

2.2.2 第一步：建立 VPN 控制连接（物理网卡）​

\n

你在家电脑上启动 VPN 客户端，输入公司 VPN 服务器的地址（公网 IP 203.0.113.5）和认证信息（用户名/密码或证书）。

\n

你家电脑客户端会通过物理网卡（IP 192.168.1.100）向 203.0.113.5 发起一个普通的网络连接。这个连接使用的是什么协议？通常是 TCP 或 UDP，比如 OpenVPN 默认用 UDP 1194 端口，或者 IKEv2 用 UDP 500 端口。

\n

数据包的样子（从你家电脑物理网卡发出）：

\n\n

这个包先到你家路由器（192.168.1.1），路由器做 NAT，把源 IP 换成自己的公网 IP 198.51.100.10，并记住映射。然后包通过互联网到达 VPN 服务器 203.0.113.5。

\n

VPN 服务器收到后，验证身份，双方完成握手，建立了一个加密的隧道。此时，在操作系统层面，你家电脑和 VPN 服务器之间已经有一条逻辑上的连接了（基于 UDP 或 TCP）。但此时还不能访问公司内网，因为还没有虚拟网卡。

\n

2.2.3 第二步：创建虚拟网卡并分配 IP​

\n

VPN 客户端软件会在你的电脑上创建一个虚拟网络接口（也叫虚拟网卡）。这个虚拟网卡在操作系统中看起来就像一个普通的网卡，但它没有物理实体，所有发给它的数据包都会被 VPN 客户端软件拦截并处理。

\n

创建好虚拟网卡后，VPN 服务器会通过刚才建立的隧道，给这个虚拟网卡分配一个公司内网的 IP 地址。比如服务器告诉客户端：“你的虚拟网卡 IP 是 192.168.10.100，子网掩码是 255.255.255.0。”

\n

客户端收到后，就在操作系统中配置这个虚拟网卡：

\n\n

此时，你家电脑就有了两个 IP 地址：

\n\n

关键点：这个 192.168.10.100 是 VPN 服务器从公司内网地址池中分配的，它在公司内网是唯一的。其他公司内网的设备（如服务器 192.168.10.5）看到这个 IP，就会认为它是公司内网的一台设备。

\n

2.2.4 第三步：修改路由表​

\n

操作系统依靠路由表来决定一个数据包应该从哪个网卡发送出去。VPN 客户端会自动添加一条或几条路由规则，让访问公司内网的流量走虚拟网卡。

\n

例如，添加一条路由：

\n\n

这样一来，当你在家电脑上访问 192.168.10.5 时，操作系统检查路由表，发现目标 IP 192.168.10.5 匹配 192.168.10.0/24，于是决定将数据包交给虚拟网卡处理。

\n

对于其他流量（比如访问百度 1.2.3.4），默认路由仍然指向物理网卡（默认路由），走你家宽带。

\n

2.2.5 第四步：访问公司内网服务器的完整数据包旅程​

\n

现在，你在家电脑上打开浏览器，输入 \\\\192.168.10.5\\share（Windows 共享）或者直接 ping 192.168.10.5，我们以 ping 为例（ICMP 协议），看看数据包怎么走。

\n
2.2.5.1 从应用程序到 IP 层​
\n

你在命令行输入 ping 192.168.10.5。操作系统生成一个 ICMP 请求数据包，这个包的 IP 头部是：

\n\n

此时，这个 IP 包（我们叫它原始包）刚刚在 IP 层生成，还没有交给任何网卡。操作系统查询路由表，发现目标 192.168.10.5 匹配 192.168.10.0/24，决定通过虚拟网卡发送。

\n

于是，原始包被交给虚拟网卡的驱动程序。

\n
2.2.5.2 虚拟网卡的处理（加密与封装）​
\n

虚拟网卡驱动程序收到这个原始包后，并不像物理网卡那样直接发送到网线上。相反，它把原始包（整个 IP 包，包括 IP 头和 ICMP 数据）交给 VPN 客户端软件。

\n

VPN 客户端软件对这个原始包进行加密和封装。封装的意思是：把整个原始包当作数据，再在外面套上一个新的 IP 头（也可能有 UDP 头）。这个新 IP 头的目标是 VPN 服务器的公网 IP。

\n

具体过程：

\n\n
2.2.5.3 外层包通过物理网卡发送​
\n

VPN 客户端软件将外层包交给操作系统的 IP 层，此时目标 IP 是 203.0.113.5，操作系统再次查询路由表，这次发现目标 IP 不在公司内网，而是公网地址，于是走默认路由，通过物理网卡发送。

\n

物理网卡驱动程序把外层包变成电信号，发送到你家路由器。路由器做 NAT，将源 IP 192.168.1.100 换成公网 IP 198.51.100.10，然后发向互联网，最终到达 VPN 服务器 203.0.113.5。

\n
2.2.5.4 VPN 服务器解包和转发​
\n

VPN 服务器收到外层包，根据 UDP 端口和协议知道这是 VPN 流量。它用自己的 VPN 服务程序处理：

\n\n
2.2.5.5 响应包返回​
\n

文件服务器 192.168.10.5 收到 ICMP 请求，生成一个 ICMP 响应，目标 IP 是 192.168.10.100（你家电脑的虚拟网卡 IP）。这个响应包在内网中传输，根据路由会到达 VPN 服务器（因为 VPN 服务器通常也是内网网关或知道路由）。

\n

VPN 服务器收到响应包（源 192.168.10.5，目标 192.168.10.100），它知道 192.168.10.100 对应的是哪个 VPN 客户端（通过维护的映射表）。于是它对这个响应包做同样的加密和封装：

\n\n

你家路由器收到后，根据 NAT 表，将外层包转发给内网的家电脑 192.168.1.100。家电脑物理网卡收到，交给操作系统，操作系统根据 UDP 端口识别是 VPN 流量，交给 VPN 客户端。VPN 客户端解包、解密，得到原始的 ICMP 响应包（源 192.168.10.5，目标 192.168.10.100）。然后 VPN 客户端把这个原始包交给虚拟网卡，虚拟网卡再把它向上传递到 IP 层，最终 ping 命令收到响应。

\n

2.2.6 总结 IP 的来源与角色​

\n\n

关键点：

\n\n

2.3 应用场景​

\n\n
\n

3. 内网穿透的本质和工作原理​

\n

3.1 本质​

\n

内网穿透解决的正是 NAT 带来的“外网无法主动访问内网设备”的问题。
\n它的目标不是让你设备“进入”另一个网络，而是把内网里的某个特定服务（比如远程桌面、Web 服务）“暴露”到公网上，让外网的人能访问到这个服务。

\n

3.2 原理（以向日葵/ToDesk 为例）​

\n\n

关键点：

\n\n

3.3 应用场景​

\n\n
\n

4. 从 OSI 模型看区别​

\n

用 OSI 七层模型（或 TCP/IP 五层模型）来定位，会更清晰：

\n
层次VPN内网穿透
网络层（IP）VPN 在这里工作：它创建虚拟网络接口，修改路由表，对 IP 包进行封装（隧道）。内网穿透一般不管 IP 层，它处理的是更上层的数据。
传输层（TCP/UDP）VPN 隧道本身可能基于 UDP 或 TCP，但 VPN 传输的是完整的 IP 包，所以包含了传输层信息。内网穿透工具通常直接转发 TCP 或 UDP 的数据流，但它不模拟网络层连接。
应用层（HTTP、RDP 等）VPN 不关心具体应用，它只是透明地传递任何上层协议的数据。内网穿透往往针对特定应用（如远程桌面协议），或者提供一个端口转发，把应用层数据原样传递。
\n
\n

5. 一个生动的比喻​

\n\n
\n

6. 总结本质区别​

\n
维度VPN内网穿透
核心目的让远程设备融入目标网络，获得内网身份，可访问所有资源。让外网用户访问内网中的特定服务。
网络层次网络层/数据链路层（虚拟网卡、路由表修改）。应用层（端口转发/代理）。
接入方式设备获得内网 IP，路由表修改，所有内网流量自动走隧道。不改变设备 IP，只转发特定应用的通信。
是否需要公网服务器通常需要 VPN 服务器有公网 IP（或双方都有公网 IP 直连）。几乎一定需要公网服务器作为协调或中继。
安全性加密整个 IP 包，隧道内所有通信都受保护。加密取决于应用实现，通常只加密应用数据。
典型产品OpenVPN, WireGuard, Cisco AnyConnect向日葵, ngrok, frp
\n", "url": "https://devvv.cn/blog/network-vpn-and-internet-tunneling-principles", "title": "VPN和内网穿透原理", "summary": "这是VPN和内网穿透原理", "date_modified": "2026-03-19T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "网络原理", "vpn", "内网穿透" ] }, { "id": "https://devvv.cn/blog/build-a-personal-site-with-astro-and-starlight", "content_html": "

为什么选择 Astro + Starlight？​

\n

官网：https://docs.astro.build/zh-cn/install-and-setup/

\n
需求Astro + Starlight 如何满足
官网、产品介绍Astro 天生适合营销页面，支持岛屿架构，可自由定制首页和产品页
API 文档Starlight 内置文档主题，配合 starlight-openapi 插件可从 OpenAPI 规范自动生成 API 文档
技术文章与书籍Starlight 完美支持 Markdown/MDX，内置搜索和导航
知识库文档即知识库，支持版本化、多级侧边栏
App 落地页可创建独立页面，支持响应式设计，Astro 静态生成性能极佳
API 开放平台可通过 Astro 的实时内容集合从后端获取动态数据
对接 Spring BootAstro 支持从 API 获取数据，可轻松对接后端接口
\n

核心优势：Astro 作为基础框架提供高性能和灵活性，Starlight 提供开箱即用的文档功能，插件生态补齐 API 文档、博客等能力 。Astro 5.10+ 的实时内容集合让可以按需从后端获取数据，实现静态与动态的完美结合 。

\n

一、环境准备​

\n

确保已安装：

\n\n
node --version
npm --version
bash
\n

输出：

\n
终端输出text
vv@jjc:~/桌面/vv/web$ node --version
v24.14.0
vv@jjc:~/桌面/vv/web$ npm --version
11.9.0
\n

二、创建 Astro + Starlight 项目​

\n

https://github.com/withastro/astro

\n

官方模板链接(全部模板)：https://astro.build/themes/

\n

官方模板链接(免费模板)：https://astro.build/themes/1/

\n

Starlight 社区资源链接：https://starlight.astro.build/resources/community-content/

\n

以下模板聚合网站定期更新 Astro 模板榜单，且已验证兼容性：

\n

AdminLTE.IO：

\n\n

Statichunt：

\n\n

Astrowind：(https://github.com/arthelokyo/astrowind)[https://github.com/arthelokyo/astrowind]

\n

1. 初始化项目​

\n
# 使用 Starlight 模板创建项目
npm create astro@latest -- --template starlight

# 按照提示操作：
# - 输入项目名称（例如：FriendlyWebV2）
# - 选择 TypeScript（推荐 Yes）
# - 选择初始化 Git（推荐 Yes）
bash
\n

2. 启动开发环境​

\n
pnpm start
bash
\n

访问 http://localhost:4321 查看默认文档站。

\n

Mizuki​

\n

https://github.com/matsuzaka-yuki/mizuki

\n

在开始使用 Mizuki 之前，您需要确保系统满足以下要求：

\n\n

集成步骤：

\n
git clone https://github.com/matsuzaka-yuki/mizuki.git
cd Mizuki

npm install -g pnpm  # 如果没安装 pnpm
pnpm install
bash
\n

然后复制根目录下的 .env.example 文件并重命名为 .env，之后启动项目：

\n
pnpm dev
bash
\n

打包则运行以下命令将网站打包成静态文件，生成到 dist 目录中：

\n
pnpm build
bash
\n

生成的 dist 目录可以部署到自己的服务器上。

", "url": "https://devvv.cn/blog/build-a-personal-site-with-astro-and-starlight", "title": "Astro + Starlight 搭建个人站点", "summary": "Astro + Starlight 搭建个人站点", "date_modified": "2026-03-13T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Astro", "TypeScript‌", "React" ] }, { "id": "https://devvv.cn/blog/docsaurus-build-self-site-record", "content_html": "

官网：https://www.docusaurus.cn/

\n

1. 进入项目目录​

\n
# 创建新项目
npx create-docusaurus@latest FriendlyWeb classic

# 进入项目目录
cd FriendlyWeb

# 如果不使用 docker
# 启动开发服务器
npm run start
# 打包
npm run build
# 如果缺少依赖，例如：找不到 prismjs 
npm install prism-react-renderer@^2.4.1
bash
\n
项目结构text
docusaurus.config.ts      # 网站配置文件
sidebars.ts              # 侧边栏配置
package.json             # 项目依赖和脚本
package-lock.json        # 锁定依赖版本（重要！）
tsconfig.json            # TypeScript 配置
README.md                # 项目说明
blog/                    # 博客文章（你的内容）
docs/                    # 文档内容（你的内容）
src/                     # 源代码（自定义组件、页面）
static/                  # 静态资源（图片、文件等）

node_modules/            # 体积巨大，可以在服务器上通过 npm install 重新生成
\n

2. Docker 配置​

\n

创建 Dockerfile（项目根目录）：

\n
Dockerfiledockerfile
# syntax=docker/dockerfile:1

# Stage 1: 基础镜像
FROM node:20-bookworm AS base
ENV FORCE_COLOR=0
ENV NODE_ENV=development
RUN corepack enable
WORKDIR /app

# Stage 2: 开发环境
FROM base AS development
# 复制依赖文件
COPY package*.json ./
# 安装所有依赖（包括开发依赖）
RUN npm install
# 暴露开发服务器端口
EXPOSE 3000
# 启动开发服务器（热重载已配置）
CMD [\"npm\", \"run\", \"start\", \"--\", \"--host\", \"0.0.0.0\", \"--poll\", \"1000\"]

# Stage 3: 构建生产版本
FROM base AS build
# 设置生产环境
ENV NODE_ENV=production
# 复制依赖文件
COPY package*.json ./
# 只安装生产依赖（更小体积）
RUN npm ci --omit=dev
# 复制源代码
COPY . .
# 构建静态文件
RUN npm run build

# Stage 4: 生产环境
FROM nginx:stable-alpine AS production
# 复制构建产物
COPY --from=build /app/build /usr/share/nginx/html
# 复制 nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf
# 暴露端口
EXPOSE 80
CMD [\"nginx\", \"-g\", \"daemon off;\"]
\n

创建 docker-compose.yml（项目根目录）：

\n
docker-compose.ymlyaml
# version: '3.8'

services:
  # 开发服务
  blog-dev:
    build:
      context: .
      target: development
      dockerfile: Dockerfile
    container_name: blog-dev
    ports:
      - \"3000:3000\"      # 网站主端口
      - \"35729:35729\"    # 热重载 live-reload 端口
    volumes:
      # 挂载源代码（选择性挂载，避免覆盖 node_modules）
      - ./blog:/app/blog
      - ./docs:/app/docs
      - ./src:/app/src
      - ./static:/app/static
      - ./docusaurus.config.ts:/app/docusaurus.config.ts
      - ./sidebars.ts:/app/sidebars.ts
      - ./tsconfig.json:/app/tsconfig.json
      - ./package.json:/app/package.json
      # 不挂载 node_modules，使用容器内的
    environment:
      - NODE_ENV=development
      - CHOKIDAR_USEPOLLING=true  # 文件监听优化
    stdin_open: true
    tty: true
    restart: unless-stopped

  # 生产预览服务（可选）
  blog-prod:
    build:
      context: .
      target: production
      dockerfile: Dockerfile
    container_name: blog-prod
    ports:
      - \"8080:80\"
    environment:
      - NODE_ENV=production
    restart: unless-stopped
\n

创建 nginx.conf（项目根目录，用于生产环境）：

\n
nginx.confnginx
server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

    # 开启 gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript 
                application/javascript application/xml+rss 
                application/json application/xml;

    # 安全 headers
    add_header X-Frame-Options \"SAMEORIGIN\" always;
    add_header X-Content-Type-Options \"nosniff\" always;
    add_header X-XSS-Protection \"1; mode=block\" always;

    # 处理 SPA 路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location /assets/ {
        expires 1y;
        add_header Cache-Control \"public, immutable\";
    }

    location /blog/ {
        expires 1y;
        add_header Cache-Control \"public, immutable\";
    }

    location /img/ {
        expires 1y;
        add_header Cache-Control \"public, immutable\";
    }

    # 健康检查
    location /health {
        access_log off;
        return 200 \"healthy\\n\";
        add_header Content-Type text/plain;
    }

    # 禁止访问隐藏文件
    location ~ /\\. {
        deny all;
        access_log off;
        log_not_found off;
    }
}
\n

创建 .dockerignore（项目根目录）：

\n
.dockerignoretext
node_modules
build
dist
logs
coverage
tmp
temp
README.md
docker-compose*.yml
.docusaurus
.git
.github
.gitignore
.vscode
.idea
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.DS_Store
.dockerignore
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
*.swp
*.swo
*~
Thumbs.db
\n

3. VSCode 开发环境配置​

\n

安装 Dev Containers 扩展。

\n

创建 .devcontainer/devcontainer.json（项目根目录）：

\n
.devcontainer/devcontainer.jsonjson
{
  \"name\": \"FriendlyWeb Development\",
  \"dockerComposeFile\": \"../docker-compose.yml\",
  \"service\": \"blog-dev\",
  \"workspaceFolder\": \"/app\",
  \"shutdownAction\": \"stopCompose\",
  \"extensions\": [
    \"dbaeumer.vscode-eslint\",
    \"esbenp.prettier-vscode\",
    \"bradlc.vscode-tailwindcss\",
    \"ms-vscode.vscode-typescript-next\"
  ],
  \"settings\": {
    \"terminal.integrated.defaultProfile.linux\": \"bash\",
    \"editor.formatOnSave\": true,
    \"editor.defaultFormatter\": \"esbenp.prettier-vscode\",
    \"typescript.tsdk\": \"node_modules/typescript/lib\",
    \"files.watcherExclude\": {
      \"**/node_modules/**\": true,
      \"**/.git/objects/**\": true,
      \"**/.git/subtree-cache/**\": true,
      \"**/build/**\": true
    }
  },
  \"forwardPorts\": [3000, 35729],
  \"postCreateCommand\": \"npm install\",
  \"remoteUser\": \"node\"
}
\n

4. TypeScript 配置​

\n

创建 tsconfig.json（项目根目录）：

\n
tsconfig.jsonjson
{
  // This file is not used in compilation. It is here just for a nice editor experience.
  \"extends\": \"@docusaurus/tsconfig\",
  \"compilerOptions\": {
    \"baseUrl\": \".\",
    \"jsx\": \"react-jsx\",
    \"paths\": {
      \"@site/*\": [\"*\"]
    }
  },
  \"types\": [
    \"@docusaurus/module-type-aliases\",
    \"@docusaurus/theme-classic\"
  ],
  \"exclude\": [\".docusaurus\", \"build\"]
}
\n

创建 src/types.d.ts（类型声明文件）：

\n
src/types.d.tstypescript
/// <reference types=\"@docusaurus/module-type-aliases\" />
/// <reference types=\"@docusaurus/theme-classic\" />

declare module \"*.md\" {
  import type { ComponentType } from \"react\";
  
  export const metadata: {
    title?: string;
    description?: string;
    permalink?: string;
    date?: Date;
    tags?: Array<{ label: string; permalink: string }>;
    [key: string]: unknown;
  };

  export const toc: Array<{
    value: string;
    id: string;
    level: number;
  }>;

  const Component: ComponentType;
  export default Component;
}

declare module \"*.mdx\" {
  export * from \"*.md\";
}
\n

5. docusaurus.config.ts​

\n
docusaurus.config.tstypescript
import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'vv的博客',
  tagline: '记录技术与生活',
  favicon: 'img/favicon.ico',

  future: {
    v4: true, 
  },

  url: 'https://your-docusaurus-site.example.com',
  baseUrl: '/',

  organizationName: 'your-github-name',
  projectName: 'your-repo-name',

  onBrokenLinks: 'throw',
  markdown: {
    mermaid: true,
    hooks: {
      onBrokenMarkdownLinks: 'warn',
    },
  },

  i18n: {
    defaultLocale: 'zh-CN',
    locales: ['zh-CN'],
  },

  presets: [
    [
      'classic',
      {
        docs: {
         sidebarPath: require.resolve('./sidebars.js'),
          editUrl: '#',
          showLastUpdateTime: false,   // 显示最后更新时间
          showLastUpdateAuthor: false,  // 显示最后更新作者
        },
        blog: {
          showReadingTime: true,
          feedOptions: {
            type: ['rss', 'atom'],
            xslt: true,
          },
          editUrl: '#',
          onInlineTags: 'warn',
          onInlineAuthors: 'warn',
          onUntruncatedBlogPosts: 'warn',
          blogSidebarTitle: '最新文章',
          blogSidebarCount: 5
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        sitemap: {
          changefreq: 'weekly',
          priority: 0.5,
        },
      } satisfies Preset.Options,
    ],
  ],

    // 添加多实例插件 - 支持多本书
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docker-book',
        path: 'books/docker_practice',
        routeBasePath: 'books/docker_practice',
        sidebarPath: require.resolve('./sidebars-docker.js'),
        editUrl: '#',
        showLastUpdateTime: false,
        showLastUpdateAuthor: false,
      },
    ],
    // 以后可以添加更多书籍
    // [
    //   '@docusaurus/plugin-content-docs',
    //   {
    //     id: 'kubernetes-book',
    //     path: 'books/kubernetes_handbook',
    //     routeBasePath: 'books/kubernetes_handbook',
    //     sidebarPath: require.resolve('./sidebars-kubernetes.js'),
    //   },
    // ],
  ],

  themeConfig: {
    image: 'img/docusaurus-social-card.jpg',
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    tableOfContents: {
      minHeadingLevel: 2,  // 从 h2 开始显示
      maxHeadingLevel: 5,  // 最多显示到 h5
    },
    navbar: {
      title: '我的博客',
      logo: {
        alt: 'vv的博客',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'tutorialSidebar',
          position: 'left',
          label: '文档',
        },
        {to: '/blog', label: '博客', position: 'left'},
        {
          type: 'dropdown',
          label: '📚 技术书籍',
          position: 'left',
          items: [
            {
              type: 'docSidebar',
              sidebarId: 'dockerBookSidebar',
              docsPluginId: 'docker-book', 
              label: '🐳 Docker — 从入门到实践',
            },
            // 可以添加更多书籍
            // {
            //   type: 'docSidebar',
            //   sidebarId: 'kubernetesBookSidebar',
            //   label: '☸️ Kubernetes 指南',
            // },
          ],
        },
        {to: '/about', label: '关于', position: 'left' },
        {
          href: 'https://gitee.com/weijun233',
          label: 'GitHub',
          position: 'right',
        },
        {
          type: 'localeDropdown',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      // links: [
      //   {
      //     title: '文档',
      //     items: [
      //       {
      //         label: '介绍',
      //         to: '/docs/intro',
      //       },
      //     ],
      //   },
      //   {
      //     title: '社区',
      //     items: [
      //       { label: 'Stack Overflow', href: '#' },
      //       { label: 'Discord', href: '#' },
      //       { label: 'GitHub', href: '#' },
      //       { label: 'Twitter', href: '#' }
      //     ],
      //   },
      //   {
      //     title: '更多',
      //     items: [
      //       {
      //         label: '博客',
      //         to: '/blog',
      //       },
      //       {
      //         label: 'GitHub',
      //         href: '#',
      //       },
      //     ],
      //   },
      // ],
      copyright: `Copyright © ${new Date().getFullYear()} vv 的个人网站.`,
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['bash', 'json', 'typescript', 'javascript'],
    },
    metadata: [
      { name: 'keywords', content: '个人网站, 博客, tech' },
      { name: 'author', content: 'vv' },
    ],
  } satisfies Preset.ThemeConfig,
};

export default config;
\n

6. sidebars.ts（侧边栏配置）​

\n
sidebars.tstypescript
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)

/**
 * Creating a sidebar enables you to:
 - create an ordered group of docs
 - render a sidebar for each doc of that group
 - provide next/previous navigation

 The sidebars can be generated from the filesystem, or explicitly defined here.

 Create as many sidebars as you want.
 */
const sidebars: SidebarsConfig = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

  // But you can create a sidebar manually
  /*
  tutorialSidebar: [
    'intro',
    'hello',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-document'],
    },
  ],
   */
};

export default sidebars;
\n

7. src/css/custom.css（自定义样式）​

\n
custom.csscss
/**
 * Any CSS included here will be global. The classic template
 * bundles Infima by default. Infima is a CSS framework designed to
 * work well for content-centric websites.
 */

/* You can override the default Infima variables here. */
:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}
\n

8. package.json​

\n

主要新增了 devDependencies。

\n
package.jsonjson
{
  \"name\": \"friendly-web\",
  \"version\": \"0.0.0\",
  \"private\": true,
  \"scripts\": {
    \"docusaurus\": \"docusaurus\",
    \"start\": \"docusaurus start\",
    \"build\": \"docusaurus build\",
    \"swizzle\": \"docusaurus swizzle\",
    \"deploy\": \"docusaurus deploy\",
    \"clear\": \"docusaurus clear\",
    \"serve\": \"docusaurus serve\",
    \"write-translations\": \"docusaurus write-translations\",
    \"write-heading-ids\": \"docusaurus write-heading-ids\",
    \"typecheck\": \"tsc\"
  },
  \"dependencies\": {
    \"@docusaurus/core\": \"3.9.2\",
    \"@docusaurus/preset-classic\": \"3.9.2\",
    \"@mdx-js/react\": \"^3.0.0\",
    \"clsx\": \"^2.0.0\",
    \"prism-react-renderer\": \"^2.3.0\",
    \"react\": \"^19.0.0\",
    \"react-dom\": \"^19.0.0\"
  },
  \"devDependencies\": {
    \"@docusaurus/module-type-aliases\": \"^3.9.2\",
    \"@docusaurus/tsconfig\": \"^3.9.2\",
    \"@docusaurus/types\": \"^3.9.2\",
    \"@types/react\": \"^19.2.14\",
    \"@types/react-dom\": \"^19.2.3\",
    \"typescript\": \"~5.6.2\"
  },
  \"browserslist\": {
    \"production\": [
      \">0.5%\",
      \"not dead\",
      \"not op_mini all\"
    ],
    \"development\": [
      \"last 3 chrome version\",
      \"last 3 firefox version\",
      \"last 5 safari version\"
    ]
  },
  \"engines\": {
    \"node\": \">=20.0\"
  }
}
\n

9. 启动项目​

\n
# 构建并启动容器
docker compose up blog-dev

# 或后台运行
docker compose up -d blog-dev
bash
\n

启动完成后访问 http://localhost:3000 查看网站。

\n

10. 重启 vscode 使用 docker 环境​

\n

方法一：使用 VSCode 自动检测 (推荐)​

\n
    \n
  1. 打开 VSCode
    2. \n
  2. 打开项目文件夹 /home/vv/桌面/vv/web/FriendlyWeb
    3. \n
  3. VSCode 会检测到 .devcontainer/devcontainer.json 文件
    4. \n
  4. 点击右下角的 \"Reopen in Container\" 按钮
    5. \n
  5. VSCode 会自动构建 Docker 镜像并启动容器
    6. \n
  6. 等待容器启动完成，所有依赖会自动安装
    7. \n
\n

\"重启vscode后右下角\"

\n

方法二：手动启动​

\n

如果 VSCode 没有自动提示，可以:

\n
    \n
  1. 按 F1 打开命令面板
    2. \n
  2. 输入 Dev Containers: Reopen in Container
    3. \n
  3. 选择并确认
    4. \n
\n

已配置的扩展​

\n

.devcontainer/devcontainer.json 中已配置的扩展:

\n\n

端口映射​

\n

容器内已映射的端口(docker-compose.yml):

\n\n

在容器中运行​

\n
# 启动开发服务器 (热重载)
npm run start

# 构建生产版本
npm run build

# 预览生产构建
npm run serve

# 类型检查
npm run typecheck

# 清理缓存
npm run clear
bash
\n

11. 常用命令​

\n
# 停止开发环境
docker compose stop

# 进入容器
docker compose exec blog-dev bash

# 重启开发容器
docker compose restart blog-dev

# 查看日志
docker compose logs -f blog-dev

# 安装新依赖（在容器内执行）
docker compose exec blog-dev npm install some-package

# 构建生产版本
docker compose exec blog-dev npm run build

# 如果需要重新构建（如修改了 package.json）
docker compose build --no-cache blog-dev
docker compose up blog-dev
bash
\n
# 删除指定 container id 的容器
docker rm <container id>
# 完全清理（删除容器和卷）
docker compose down -v
bash
\n

生产版本:

\n
docker compose up blog-prod

# 构建生产镜像
docker build --target production -t my-blog:latest .

# 运行预览
docker run -p 8080:80 my-blog:latest
bash
\n

12. 打包镜像迁移环境​

\n

在旧电脑上保存镜像：

\n
# 1. 进入项目目录
cd /home/vv/桌面/vv/web/FriendlyWeb

# 查看所有镜像
docker images
# 2. 提交当前容器为镜像（包含所有安装好的依赖）
docker commit blog-dev docusaurus-dev:latest

# 查看刚刚 commit 的镜像
docker images | grep docusaurus

# 3. 保存镜像为 tar 文件
docker save docusaurus-dev:latest -o docusaurus-dev.tar

# 4. 压缩文件减小体积
gzip docusaurus-dev.tar

# 5. 查看文件大小
ls -lh docusaurus-dev2.0.tar
bash
\n

传输到新电脑上：

\n
# 使用 U 盘、scp 或其他方式传输
# 假设传输到新电脑的 /home/vv/ 目录下
scp docusaurus-dev.tar.gz vv@新电脑IP:/home/vv/
bash
\n

在新电脑上加载镜像：

\n
# 1. 解压
gunzip docusaurus-dev.tar.gz

# 2. 加载镜像
docker load -i docusaurus-dev.tar

# 3. 确认镜像已加载
docker images | grep docusaurus-dev
bash
\n

在新电脑上运行：

\n
# 1. 创建项目目录
mkdir -p ~/web/FriendlyWeb
cd ~/web/FriendlyWeb

# 2. 从旧电脑复制项目文件（除了 node_modules）
# 使用 U 盘或 scp 复制所有项目文件
scp -r vv@旧电脑IP:/home/vv/桌面/vv/web/FriendlyWeb/* ./
scp -r vv@旧电脑IP:/home/vv/桌面/vv/web/FriendlyWeb/.* ./ 2>/dev/null || true

# 3. 创建 docker-compose.yml（参考下面的配置）
bash
\n

创建 docker-compose.yml：

\n
docker-compose.ymlyaml
services:
  blog-dev:
    image: docusaurus-dev:latest  # 使用刚才加载的镜像
    container_name: blog-dev
    ports:
      - \"3000:3000\"
      - \"35729:35729\"
    volumes:
      - ./blog:/app/blog
      - ./docs:/app/docs
      - ./books:/app/books
      - ./src:/app/src
      - ./static:/app/static
      - ./docusaurus.config.ts:/app/docusaurus.config.ts
      - ./sidebars.ts:/app/sidebars.ts
      - ./sidebars-docker.js:/app/sidebars-docker.js
      - ./tsconfig.json:/app/tsconfig.json
      - ./package.json:/app/package.json
    environment:
      - NODE_ENV=development
      - CHOKIDAR_USEPOLLING=true
    stdin_open: true
    tty: true
    restart: unless-stopped
\n

启动开发环境：

\n
docker compose up -d blog-dev
docker compose logs -f blog-dev
bash
\n

13. 安装插件​

\n

安装 Mermaid 主题​

\n
docker compose exec blog-dev bash
npm install @docusaurus/theme-mermaid
exit
bash
\n

检查你的 docusaurus.config.ts 中是否启用了 Mermaid：

\n
docusaurus.config.tstypescript
const config: Config = {
  // ... 其他配置
  markdown: {
    mermaid: true,
  },
  themes: [
    '@docusaurus/theme-mermaid',
  ],
};
\n
docker stop blog-dev
docker compose up blog-dev
bash
\n

安装搜索插件​

\n

链接：https://github.com/easyops-cn/docusaurus-search-local

\n
docker compose exec blog-dev bash
npm install --save @easyops-cn/docusaurus-search-local
npm list --depth=0 | grep docusaurus-search-local
exit
bash
\n

配置 docusaurus.config.ts：

\n
docusaurus.config.tstypescript
const config: Config = {
  // ... 其他配置
  themes: [
    // ... 其他主题
    [
      require.resolve(\"@easyops-cn/docusaurus-search-local\"),
      {
        indexDocs: true,  // 是否索引文档
        indexBlog: true,  // 是否索引博客
        indexPages: false,  // 是否索引静态页面
        language: [\"en\", \"zh\"], // 中文文档推荐配置
        hashed: true, // 添加哈希以便长期缓存
        searchResultLimits: 8,  // 搜索结果数量
        searchResultContextMaxLength: 50, // 搜索结果上下文长度
        searchBarShortcutHint: true,  // 是否显示键盘快捷键提示
        // 自定义快捷键 (可选)
        // searchBarShortcutKeymap: \"mod+k\",
      }
    ],
  ],
};
\n

已废弃的方案​

\n
npm install @cmfcmf/docusaurus-search-local
npm uninstall @cmfcmf/docusaurus-search-local
npm list --depth=0 | grep docusaurus-search-local # 验证是否安装成功
# 如果需要中文，需要安装 nodejieba
npm install nodejieba # (已被废弃)
npm uninstall nodejieba
bash
\n

修改 docusaurus.config.ts：

\n
docusaurus.config.tstypescript
const config: Config = {
  // ... 其他配置
  plugins: [
    // 有的其他插件
    [
      '@docusaurus/plugin-content-docs',
      // ... 书籍插件配置
    ],
    [
      '@cmfcmf/docusaurus-search-local',
      {
        indexDocs: true,  // 是否索引文档页面
        indexBlog: true,  // 是否索引博客页面
        indexPages: false,  // 是否索引静态页面
        language: 'zh',   // 文档语言，中文用 'zh'
        maxSearchResults: 8,  // 搜索结果数量
        // Lunr.js 搜索配置
        lunr: {
          titleBoost: 5,  // 标题匹配权重
          contentBoost: 1,  // 内容匹配权重
          tagsBoost: 3,  // 标签匹配权重
        }
      },
    ],
  ],
};
\n

14. 安装 Remark 数学插件​

\n
docker compose exec blog-dev bash
npm install remark-math rehype-katex
npm list remark-math rehype-katex  # 检查是否安装成功
# 如果需要，重新安装指定版本
npm install --save remark-math@6 rehype-katex@7
exit
bash
\n

然后修改 docusaurus.config.ts：

\n
docusaurus.config.tstypescript
const remarkMath = require('remark-math');
const rehypeKatex = require('rehype-katex');

const config: Config = {
  // ... 其他配置
  presets: [
    [
      'classic',
      {
        docs: {
         sidebarPath: require.resolve('./sidebars.js'),
          editUrl: '#',
          showLastUpdateTime: false,   // 显示最后更新时间
          showLastUpdateAuthor: false,  // 显示最后更新作者
          // 添加数学公式插件
          remarkPlugins: [remarkMath],
          rehypePlugins: [rehypeKatex],
        },
        blog: {
          showReadingTime: true,
          feedOptions: {
            type: ['rss', 'atom'],
            xslt: true,
          },
          editUrl: '#',
          onInlineTags: 'warn',
          onInlineAuthors: 'warn',
          onUntruncatedBlogPosts: 'warn',
          blogSidebarTitle: '最新文章',
          blogSidebarCount: 5,
          // 博客也启用数学公式
          remarkPlugins: [remarkMath],
          rehypePlugins: [rehypeKatex],
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        sitemap: {
          changefreq: 'weekly',
          priority: 0.5,
        },
      } satisfies Preset.Options,
    ],
  ],
  // 添加 KaTeX 样式
  stylesheets: [
    {
      href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
      type: 'text/css',
      integrity: 'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
      crossorigin: 'anonymous',
    },
  ],

  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docker-book',
        path: 'books/docker_practice',
        routeBasePath: 'books/docker_practice',
        sidebarPath: require.resolve('./sidebars-docker.js'),
        editUrl: '#',
        showLastUpdateTime: false,
        showLastUpdateAuthor: false,
        // 书籍也启用数学公式
        remarkPlugins: [require('remark-math')],
        rehypePlugins: [require('rehype-katex')],
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'ai-beginner-guide-book',
        path: 'books/ai_beginner_guide',
        routeBasePath: 'books/ai_beginner_guide',
        sidebarPath: require.resolve('./sidebars-aibeginner.js'),
        editUrl: '#',
        showLastUpdateTime: false,
        showLastUpdateAuthor: false,
        remarkPlugins: [require('remark-math')],
        rehypePlugins: [require('rehype-katex')],
      },
    ],
  ],
};
\n
docker stop blog-dev
docker compose up blog-dev
bash
\n

15. 最终打包静态资源步骤​

\n
cd /home/vv/桌面/vv/web/FriendlyWeb
docker compose up blog-dev
docker compose exec blog-dev bash
# 进入容器后
cd /app
npm run build
exit
./copy_build.sh
# 运行一个临时 Nginx 容器来提供 build 目录下的文件
docker run --rm -p 8081:80 -v \"$(pwd)/build:/usr/share/nginx/html:ro\" nginx:alpine

# 打包 build 目录
tar -czf friendlyweb-build.tar.gz build/
# 查看文件大小
ls -lh friendlyweb-build.tar.gz
bash
\n

命令解释：\n--rm: 容器停止后自动删除，不留垃圾 。\n-p 8081:80: 将宿主机的 8081 端口映射到容器的 80 端口 。访问 http://localhost:8081 即可。\n-v \"$(pwd)/build:/usr/share/nginx/html:ro\": 这是核心。它将你当前目录下的 build 文件夹挂载到 Nginx 容器内的默认网站根目录，ro 表示只读，确保容器不会修改你的文件 。\nnginx:alpine: 使用基于 Alpine Linux 的轻量级 Nginx 镜像，下载快，体积小。

\n

运行后，打开浏览器访问 http://localhost:8081 就能看到网站了。

\n

打包完成后，静态文件生成在：build/ 目录:

\n
文件结构text
FriendlyWeb/
├── build/                    # 👈 打包后的静态文件在这里
│   ├── index.html            # 首页
│   ├── blog/                 # 博客页面
│   ├── docs/                 # 文档页面
│   ├── books/                # 书籍页面
│   ├── assets/               # 静态资源（CSS、JS等）
│   │   ├── css/
│   │   ├── js/
│   │   └── images/
│   └── ...
├── books/
├── src/
└── ...
\n
# 进入容器
docker compose run --rm blog-dev bash
# 相当于：临时启动一个新容器
# - 即使 blog-dev 没运行，也会启动新容器
# - 不继承 ports 配置（不会映射端口）
# - 继承 volumes 配置
# - 退出 bash 后容器自动删除（--rm）

# 进入容器
docker compose exec blog-dev bash
# 相当于：进入正在运行的容器
# - 容器必须已经运行（docker ps 能看到）
# - 所有端口映射、挂载卷都保持
# - 退出 bash 不会停止容器
# 执行打包命令
bash
\n

16. 自定义页面​

\n

安装必要插件：

\n
docker compose exec blog-dev bash
npm install @iconify/react framer-motion tailwindcss@^3 postcss@^8 autoprefixer@^10 @tailwindcss/typography mini-svg-data-uri tailwind-merge copy-text-to-clipboard react-icon-cloud
npm install -D typescript @types/react @types/react-dom @types/node
# 代码高亮
npm install prism-react-renderer@^2.4.1
npm install --save prism-react-renderer

# 这个插件自动生效，安装配置后，用户点击网站上的图片就会自动放大显示。
npm install docusaurus-plugin-image-zoom  
# 这个插件不会自动生效，需要在代码中显式使用其提供的组件。主要用于优化图片加载性能。
npm install @docusaurus/plugin-ideal-image

exit
bash
\n

检查你的 docusaurus.config.ts 中是否启用了 Mermaid：

\n
docusaurus.config.tstypescript
const config: Config = {
  // ... 其他配置
  markdown: {
    mermaid: true,
  },
  themes: [
    '@docusaurus/theme-mermaid',
  ],
};
\n
docker stop blog-dev
docker compose up blog-dev
bash
\n

17. 图片插件使用​

\n

这两个插件一个用于实现图片点击放大功能，另一个用于图片性能优化，我来给你详细说明：

\n
\n

1. docusaurus-plugin-image-zoom​

\n

安装依赖​

\n
npm install docusaurus-plugin-image-zoom
bash
\n

在哪里使用​

\n

这个插件自动生效，安装配置后，用户点击网站上的图片就会自动放大显示。

\n

配置方法​

\n

在 docusaurus.config.ts 中配置：

\n
docusaurus.config.tstypescript
const config: Config = {
  // 在 plugins 数组中添加
  plugins: [
    'docusaurus-plugin-image-zoom',
    // ...其他插件
  ],
  
  // 在 themeConfig 中添加 zoom 配置
  themeConfig: {
    zoom: {
      selector: '.markdown :not(em) > img',  // 选择哪些图片可缩放
      background: {
        light: 'rgb(255, 255, 255)',  // 浅色模式背景
        dark: 'rgb(50, 50, 50)'       // 深色模式背景
      },
      config: {
        // medium-zoom 的配置选项
        // margin: 24,
        // scrollOffset: 0,
      }
    },
    // ...其他配置
  }
}
\n

配置参数说明​

\n
参数说明默认值
selector选择哪些图片应用缩放功能.markdown img
background缩放时的背景颜色{ light: '#fff', dark: '#222' }
configmedium-zoom 库的配置选项{}
\n
\n

📌 这个插件基于 medium-zoom 库实现，你可以在 medium-zoom 文档 查看更多配置选项。

\n
\n

2. @docusaurus/plugin-ideal-image​

\n

安装依赖​

\n
npm install @docusaurus/plugin-ideal-image
bash
\n

在哪里使用​

\n

这个插件不会自动生效，需要在代码中显式使用其提供的组件。主要用于优化图片加载性能。

\n

配置方法​

\n

在 docusaurus.config.ts 中配置：

\n
docusaurus.config.tstypescript
const config: Config = {
  plugins: [
    [
      '@docusaurus/plugin-ideal-image',
      {
        quality: 85,           // JPEG 压缩质量
        max: 1030,             // 最大图片宽度
        min: 640,              // 最小图片宽度
        steps: 4,              // 生成图片尺寸的数量
        disableInDev: false,   // 开发模式下是否启用（默认 true 表示禁用）
      },
    ],
    // ...其他插件
  ],
}
\n

使用方法​

\n

在 MDX/Markdown 中，不能直接使用 ![alt](image.png)，需要使用 @theme/IdealImage 组件：

\n
使用 IdealImagemdx
import Image from '@theme/IdealImage';
import myImage from './path/to/image.png';

// 使用 IdealImage 组件
<Image img={myImage} />

// 或使用 require
<Image img={require('./path/to/image.png')} />
\n

在 JSX/TSX 组件中：

\n
使用 IdealImagetsx
import Image from '@theme/IdealImage';
import thumbnail from './img/thumbnail.png';

export default function MyComponent() {
  return (
    <div>
      <Image img={thumbnail} />
    </div>
  );
}
\n

配置参数说明​

\n
参数说明默认值
name输出文件命名模板ideal-img/[name].[hash:hex:7].[width].[ext]
sizes指定生成的图片尺寸数组原始尺寸
min最小图片宽度-
max最大图片宽度-
stepsmin 和 max 之间生成的图片数量4
qualityJPEG 压缩质量85
disableInDev开发模式禁用（提升开发体验）true
\n

⚠️ 重要注意事项​

\n
    \n
  1. 仅支持 PNG 和 JPG 格式
    2. \n
  2. 开发模式下默认不生效：为了开发体验，开发模式下图片不会进行优化处理。如需调试，设置 disableInDev: false
    3. \n
  3. 导入图片类型会改变：\n\n
    4. \n
  4. 如果使用 pnpm：需要配置 onlyBuiltDependencies 来确保 sharp 依赖正确安装
    5. \n
\n
package.jsonjson
// package.json
{
  \"pnpm\": {
    \"onlyBuiltDependencies\": [\"fsevents\"]
  }
}
\n

两个插件的功能对比​

\n
功能image-zoomideal-image
图片点击放大✅ 主要功能❌
响应式图片（不同屏幕尺寸）❌✅
懒加载❌✅
低质量占位符❌✅
自动 WebP 转换❌✅
使用方式自动生效需要手动使用 <Image> 组件
\n

两个插件可以同时使用，互不冲突。ideal-image 负责优化图片加载性能，image-zoom 负责提供点击放大的交互体验。

", "url": "https://devvv.cn/blog/docsaurus-build-self-site-record", "title": "Docusaurus 搭建个人站点", "summary": "Docusaurus 搭建个人站点", "date_modified": "2026-03-12T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Docusaurus", "TypeScript‌", "React" ] }, { "id": "https://devvv.cn/blog/install-npm-and-nvm", "content_html": "

安装​

\n
sudo apt update
sudo apt install -y nodejs npm
npm install -g pnpm # 如果没权限，先 sudo -i 切换到 root

# 验证安装
node -v
npm -v
pnpm --version
bash
\n

升级​

\n
# 升级npm到最新稳定版
npm install -g npm@latest

# 升级到指定的9.6.5+版本
npm install -g npm@9.6.5

# 配置国内镜像
npm config set registry https://registry.npmmirror.com
bash
\n

nvm​

\n

安装 nvm，nvm 是最灵活的 Node.js 版本管理工具，可以轻松安装和切换多个版本：

\n
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc
# 如果使用 Zsh，则运行 source ~/.zshrc

# 验证 nvm 安装
nvm --version

# 安装最新 LTS 版本
nvm install --lts
# 这将会安装最新的长期支持版本

# 设置为默认版本
nvm alias default node

# 验证升级结果
node -v
npm -v
bash
", "url": "https://devvv.cn/blog/install-npm-and-nvm", "title": "安装 npm 和 nvm", "summary": "安装 npm 和 nvm", "date_modified": "2026-03-09T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "npm", "nvm" ] }, { "id": "https://devvv.cn/blog/git-command-record-usage", "content_html": "

查看 git 信息​

\n
git config --global user.name
git config --global user.email
bash
\n

添加 gitee@com 公钥​

\n
# -t key 类型
# -C 注释
ssh-keygen -t ed25519 -C \"Gitee SSH Key\"
# 然后连按三次回车

ls ~/.ssh/
# 私钥文件 id_ed25519
# 公钥文件 id_ed25519.pub

# 读取公钥文件
cat ~/.ssh/id_ed25519.pub
# 复制整个输出(ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAADIQHTBW8jsHPp+5FlrEdcA5eXRgclBIS+PsVVE3ysGJJ Gitee SSH Key)，添加到 gitee 公钥

# 测试输出
ssh -T git@gitee.com
# 输入 yes
# Warning: Permanently added 'gitee.com' (ED25519) to the list of known hosts.
# Hi weijun(@weijun233)! You've successfully authenticated, but GITEE.COM does not provide shell access.
bash
\n

1.查看本地有但远程没有的提交​

\n
git log origin/main..HEAD   # 如果远程分支是 main
git log origin/master..HEAD # 如果远程分支是 master

git log --oneline # 查看提交历史
git log --oneline origin/master..HEAD # 简洁显示
git log --stat origin/master..HEAD # 查看未推送提交的详细内容
git log --oneline --graph origin/master..HEAD # 图形化显示

git log @{u}.. # 查看当前分支对应的远程分支未推送的提交

git log --name-only --oneline -3 # 查看最近三次提交的文件列表
git log --stat -3 # 更详细的文件列表（含状态）
bash
\n

可以将常用命令设置为别名：

\n
# 添加到 ~/.gitconfig
[alias]
unpushed = log --oneline origin/master..HEAD
unpushed-all = log origin/master..HEAD
bash
\n

示例输出

\n
$ git log --oneline origin/master..HEAD
a1b2c3d 修复登录页面样式问题
e4f5g6h 添加用户注册功能
text
\n

2.显示未推送到远程的提交​

\n
git cherry -v
git cherry -v origin/master # 指定远程分支
bash
\n

3.显示本地领先远程多少个提交​

\n
git status -sb
# 或
git branch -vv
bash
\n

这会显示类似 [ahead 2] 的信息，表示有 2 个本地提交未推送。

\n

4.查看未推送的提交差异​

\n
git diff origin/master..HEAD
bash
\n

5.强制推送到远程​

\n
git push --force
bash
\n

6.备份当前修改​

\n
git stash
bash
\n

7.重置到远程分支的状态​

\n
git fetch origin
git reset --hard origin/master
bash
\n

8.查看未推送提交中的文件变化​

\n
# 查看所有未推送提交中的文件变化
git diff --name-only origin/master..HEAD
# 使用git show查看每个提交的文件
git show --name-only HEAD~2..HEAD 
# 查看最近三次提交的文件列表
git log --name-only --oneline -3
# 更详细的文件列表（含状态）
git log --stat -3

# 首先确认有多少个未推送的提交
git status -sb
# 输出类似: ## master...origin/master [ahead 5]
# 查看最近三次未推送提交的文件
git log --name-only --oneline HEAD~3..HEAD
# 或者使用相对引用
git log --name-only --oneline origin/master..HEAD | head -20  # 查看前三提交的大概信息
bash
\n

9.分别查看每个未推送提交的文件​

\n
# 列出最近三次提交的哈希值
git log --oneline -3

# 分别查看每个提交的文件
git show --name-only HEAD     # 最新提交的文件
git show --name-only HEAD~1   # 第二个提交的文件
git show --name-only HEAD~2   # 第三个提交的文件
bash
\n

10.舍弃已提交但未push的记录​

\n
# 完全放弃所有未push的commit和更改（⚠️ 危险操作警告）
git fetch && git reset --hard origin/$(git branch --show-current)
# git reset --hard 会永久删除以下内容：
# 1. 所有未push的commit
# 2. 所有未暂存(staged)的更改
# 3. 所有工作区的修改
# 无法用git命令恢复！除非你有stash备份
# 操作前建议备份


# 完全重置到远程分支状态（最彻底）
# 方法1：使用 git reset
git fetch origin                    # 获取远程最新状态
git reset --hard origin/master      # 如果是 master 分支

# 方法2：使用 git checkout（Git 2.23+ 推荐）
git fetch origin
git switch -f master                # 强制切换到远程状态

# 丢弃最近 N 次提交
# 查看要丢弃多少次提交
git log --oneline origin/master..HEAD
# 丢弃最近的3次提交（保留更改在工作区）
git reset --soft HEAD~3
# 丢弃最近的3次提交（完全丢弃更改）
git reset --hard HEAD~3

# 重置后检查
git status          # 应该显示 \"Your branch is up to date with 'origin/master'\"
git log --oneline   # 应该和远程分支一致
git diff origin/master # 应该没有差异
bash
", "url": "https://devvv.cn/blog/git-command-record-usage", "title": "Git 常用命令", "summary": "git 常用命令", "date_modified": "2026-03-04T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "git" ] }, { "id": "https://devvv.cn/blog/cmake-multi-module-project-configuration", "content_html": "

第一步：创建动态库项目​

\n\n

第二步：编写库的代码​

\n

CLion的库模板会生成一个简单的 library.h 和 library.cpp 文件。我们需要对其进行修改，使其成为真正的动态库。

\n

关键点：符号导出\n在Windows上创建动态库（.dll）时，需要用 __declspec(dllexport) 显式声明要导出的函数、类等，否则外部程序无法使用。而在Linux上，默认所有非静态符号都会被导出。为了编写跨平台的代码，我们通常会使用宏来处理这个差异。

\n

修改头文件 library.h：\n我们将头文件修改为如下内容，定义一个跨平台的导出宏 MATHLIB_API。

\n
library.hcpp
// library.h
#ifndef MYMATH_LIBRARY_H
#define MYMATH_LIBRARY_H

// 跨平台导出宏定义
#ifdef _WIN32 // 如果是Windows平台
#ifdef MYMATH_EXPORTS // 如果当前正在构建库
#define MATHLIB_API __declspec(dllexport)
#else // 如果是使用库
#define MATHLIB_API __declspec(dllimport)
#endif
#else // 如果是Linux/Unix平台
#define MATHLIB_API // 在Linux上，所有符号默认导出，此宏定义为空
#endif

// 使用 MATHLIB_API 宏来修饰需要导出的函数
// 这对于Linux不是必须的，但保持了代码的跨平台一致性
extern \"C\" {
MATHLIB_API int add(int a, int b);
MATHLIB_API int subtract(int a, int b);
}

#endif //MYMATH_LIBRARY_H
\n

extern \"C\" 是为了防止C++编译器对函数名进行名字改编（name mangling），这样从其他语言（或C++本身）调用这个库时会更容易，函数名也会更清晰。

\n

修改源文件 library.cpp：\n实现头文件中声明的函数。

\n
library.cppcpp
// library.cpp
#include \"library.h\"
#include <iostream>

// 定义一个宏，标记当前正在构建库，用于Windows平台
#define MYMATH_EXPORTS

int add(int a, int b) {
std::cout << \"Calling add function from dynamic library.\" << std::endl;
return a + b;
}

int subtract(int a, int b) {
std::cout << \"Calling subtract function from dynamic library.\" << std::endl;
return a - b;
}
\n

第三步：编译生成动态库​

\n\n

这里做了子模块处理：

\n\n

编译完成后，在cmake-build-debug/lib目录下会生成：

\n
lib目录结构text
liblib_test.so          → 紫色图标（软链接）→ 指向 liblib_test.so.1
liblib_test.so.1        → 紫色图标（软链接）→ 指向 liblib_test.so.1.0.0  
liblib_test.so.1.0.0    → 普通文件图标 → 真正的动态库文件
\n

编译器链接名: liblib_test.so

\n\n

第四步：新建测试项目​

\n

先执行:

\n
./build_and_install.sh -m lib_test
bash
\n

然后打开测试项目 TestSoDemo测试动态库的引用.rar 运行即可。

\n
build_and_install.shshell
#!/bin/bash

# 自动编译当前模块并安装动态库到指定目录
# 编译 lib_test 模块: ./build_and_install.sh -m lib_test

# 颜色定义，让输出更美观
RED='\\033[0;31m'
GREEN='\\033[0;32m'
YELLOW='\\033[1;33m'
BLUE='\\033[0;34m'
NC='\\033[0m' # No Color

# 目标安装目录，so 动态库存放目录
INSTALL_DIR=\"/home/vv/cpp/lib\"

# 当前目录
CURRENT_DIR=$(pwd)
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo $CURRENT_DIR)

# 显示帮助信息
show_help() {
    echo -e \"${BLUE}用法:${NC} $0 [选项] [模块名]\"
    echo
    echo -e \"${YELLOW}选项:${NC}\"
    echo \"  -h, --help     显示此帮助信息\"
    echo \"  -a, --all      编译并安装所有模块\"
    echo \"  -c, --clean    编译前先清理\"
    echo \"  -b, --build-dir 指定构建目录 (默认: ./build)\"
    echo \"  -m, --module    指定模块名 (可选)\"
    echo
    echo -e \"${YELLOW}示例:${NC}\"
    echo \"  $0                      # 编译当前目录下的模块\"
    echo \"  $0 -c module1           # 清理并编译module1\"
    echo \"  $0 -a                   # 编译所有模块\"
    echo \"  $0 -b ~/mybuild module2 # 指定构建目录\"
}

# 创建安装目录
create_install_dir() {
    if [ ! -d \"$INSTALL_DIR\" ]; then
        echo -e \"${BLUE}创建安装目录: ${INSTALL_DIR}${NC}\"
        mkdir -p \"$INSTALL_DIR\"
        if [ $? -ne 0 ]; then
            echo -e \"${RED}错误: 无法创建安装目录${NC}\"
            exit 1
        fi
    fi
}

# 查找CMakeLists.txt
find_cmakelists() {
    local search_dir=\"$1\"

    # 如果在模块目录，检查当前目录
    if [ -f \"$search_dir/CMakeLists.txt\" ]; then
        echo \"$search_dir\"
        return 0
    fi

    # 向上查找直到找到CMakeLists.txt
    local current=\"$search_dir\"
    while [ \"$current\" != \"/\" ]; do
        if [ -f \"$current/CMakeLists.txt\" ]; then
            echo \"$current\"
            return 0
        fi
        current=$(dirname \"$current\")
    done

    return 1
}

# 获取模块名（从目录名或CMakeLists.txt）
get_module_name() {
    local module_dir=\"$1\"

    # 如果指定了模块名，直接使用
    if [ -n \"$MODULE_NAME\" ]; then
        echo \"$MODULE_NAME\"
        return 0
    fi

    # 否则使用目录名作为模块名
    echo $(basename \"$module_dir\")
}

# 编译模块
build_module() {
    local module_dir=\"$1\"
    local module_name=$(get_module_name \"$module_dir\")

    echo -e \"\\n${GREEN}========== 开始编译模块: ${module_name} ==========${NC}\"

    # 进入模块目录
    cd \"$module_dir\" || {
        echo -e \"${RED}错误: 无法进入目录 ${module_dir}${NC}\"
        return 1
    }

    # 设置构建目录
    local build_dir=\"${BUILD_DIR:-$module_dir/build}\"

    # 如果需要清理
    if [ \"$CLEAN_BUILD\" = true ]; then
        echo -e \"${YELLOW}清理构建目录: ${build_dir}${NC}\"
        rm -rf \"$build_dir\"
    fi

    # 创建构建目录
    mkdir -p \"$build_dir\"
    cd \"$build_dir\" || {
        echo -e \"${RED}错误: 无法进入构建目录${NC}\"
        return 1
    }

    # 运行CMake
    echo -e \"${BLUE}配置CMake...${NC}\"
    cmake .. -DCMAKE_BUILD_TYPE=Release

    if [ $? -ne 0 ]; then
        echo -e \"${RED}CMake配置失败${NC}\"
        return 1
    fi

    # 编译
    echo -e \"${BLUE}编译中...${NC}\"
    make -j$(nproc)

    if [ $? -ne 0 ]; then
        echo -e \"${RED}编译失败${NC}\"
        return 1
    fi

    echo -e \"${GREEN}编译完成${NC}\"
    return 0
}

# 查找真正的动态库文件（带完整版本号的）
find_real_so_file() {
    local build_dir=\"$1\"
    local module_name=\"$2\"

    # 在构建目录的lib子目录或当前目录查找
    local search_dirs=(
        \"$build_dir/lib\"
        \"$build_dir\"
        \"$build_dir/src\"
    )

    for dir in \"${search_dirs[@]}\"; do
        if [ -d \"$dir\" ]; then
            # 查找带完整版本号的.so文件（如 libxxx.so.X.Y.Z）
            # 使用find命令找到真正的文件（不是软链接）
            local so_file=$(find \"$dir\" -maxdepth 1 -type f -name \"lib${module_name}.so.*.*.*\" | head -1)

            if [ -n \"$so_file\" ]; then
                echo \"$so_file\"
                return 0
            fi

            # 如果没有找到带三个版本号的，找带一个版本号的
            so_file=$(find \"$dir\" -maxdepth 1 -type f -name \"lib${module_name}.so.*\" ! -name \"*.so\" | head -1)

            if [ -n \"$so_file\" ]; then
                echo \"$so_file\"
                return 0
            fi
        fi
    done

    return 1
}

# 创建软链接（如果不存在或不正确）
create_symlink_if_needed() {
    local target=\"$1\"
    local link_name=\"$2\"
    local link_path=\"$INSTALL_DIR/$link_name\"

    # 如果软链接不存在，创建它
    if [ ! -L \"$link_path\" ]; then
        ln -s \"$target\" \"$link_path\"
        echo -e \"${GREEN}✓ 创建软链接: ${link_name} -> ${target}${NC}\"
        return 0
    fi

    # 如果软链接存在但指向错误，更新它
    local current_target=$(readlink \"$link_path\")
    if [ \"$current_target\" != \"$target\" ]; then
        ln -sf \"$target\" \"$link_path\"
        echo -e \"${YELLOW}✓ 更新软链接: ${link_name} -> ${target} (原指向: ${current_target})${NC}\"
    fi
}

# 拷贝动态库到安装目录
install_library() {
    local module_dir=\"$1\"
    local module_name=$(get_module_name \"$module_dir\")
    local build_dir=\"${BUILD_DIR:-$module_dir/build}\"

    echo -e \"\\n${BLUE}安装模块: ${module_name}${NC}\"

    # 查找真正的.so文件
    local so_file=$(find_real_so_file \"$build_dir\" \"$module_name\")

    if [ -z \"$so_file\" ]; then
        echo -e \"${RED}错误: 在构建目录中找不到 ${module_name} 的动态库文件${NC}\"
        echo -e \"${YELLOW}查找路径: ${build_dir}${NC}\"
        return 1
    fi

    echo -e \"${GREEN}找到库文件: ${so_file}${NC}\"

    # 获取文件名和路径信息
    local so_filename=$(basename \"$so_file\")
    local so_dir=$(dirname \"$so_file\")
    local target_file=\"$INSTALL_DIR/$so_filename\"
    local lib_basename=$(echo \"$so_filename\" | cut -d'.' -f1)  # 如: liblib_test
    local major_version=$(echo \"$so_filename\" | cut -d'.' -f3)  # 如: 1

    # 拷贝真正的库文件
    echo -e \"${BLUE}拷贝真正的库文件到: ${target_file}${NC}\"
    cp \"$so_file\" \"$target_file\"

    if [ $? -eq 0 ]; then
        echo -e \"${GREEN}✓ 安装成功: ${so_filename}${NC}\"

        # 进入安装目录创建软链接
        cd \"$INSTALL_DIR\" || return 1

        # 创建主版本软链接 (libxxx.so.1)
        if [ -n \"$major_version\" ]; then
            create_symlink_if_needed \"$so_filename\" \"${lib_basename}.so.${major_version}\"
        fi

        # 创建编译器软链接 (libxxx.so)
        create_symlink_if_needed \"$so_filename\" \"${lib_basename}.so\"

        # 显示最终结果
        echo -e \"\\n${BLUE}安装目录内容:${NC}\"
        ls -l \"${lib_basename}\"*

        # 返回原目录
        cd - > /dev/null

        # ========== 新增：头文件拷贝部分 ==========
        echo -e \"\\n${BLUE}处理头文件...${NC}\"

        # 定义头文件安装目录
        local INCLUDE_INSTALL_DIR=\"/home/vv/cpp/include\"

        # 创建头文件安装目录
        mkdir -p \"$INCLUDE_INSTALL_DIR\"

        echo -e \"\\n当前路径: ${module_dir}...${NC}\"

        # 查找模块中的头文件目录
        local possible_include_dirs=(
            \"$module_dir/$module_name/include\"
        )

        local header_copied=false

        for include_dir in \"${possible_include_dirs[@]}\"; do
            if [ -d \"$include_dir\" ]; then
                echo -e \"${BLUE}找到头文件目录: ${include_dir}${NC}\"

                # 创建模块专用的头文件子目录
                local module_include_dir=\"$INCLUDE_INSTALL_DIR/$module_name\"
                mkdir -p \"$module_include_dir\"

                # 拷贝所有.h文件到模块子目录
                echo -e \"${BLUE}拷贝头文件到: ${module_include_dir}${NC}\"

                # 使用rsync或cp拷贝
                if command -v rsync &> /dev/null; then
                    rsync -av --include=\"*/\" --include=\"*.h\" --include=\"*.hpp\" --exclude=\"*\" \\
                        \"$include_dir/\" \"$module_include_dir/\"
                else
                    # 如果没有rsync，用find+cp
                    find \"$include_dir\" -name \"*.h\" -o -name \"*.hpp\" | while read header; do
                        # 保持相对路径结构
                        rel_path=\"${header#$include_dir/}\"
                        target_path=\"$module_include_dir/$rel_path\"
                        target_dir=$(dirname \"$target_path\")
                        mkdir -p \"$target_dir\"
                        cp \"$header\" \"$target_path\"
                        echo \"  Copied: $rel_path\"
                    done
                fi

                # 统计拷贝的文件数
                local file_count=$(find \"$module_include_dir\" -name \"*.h\" -o -name \"*.hpp\" | wc -l)
                if [ \"$file_count\" -gt 0 ]; then
                    echo -e \"${GREEN}✓ 已安装 ${file_count} 个头文件到 ${module_include_dir}${NC}\"
                    header_copied=true
                else
                    echo -e \"${YELLOW}警告: 在 ${include_dir} 中没有找到头文件${NC}\"
                    rmdir \"$module_include_dir\" 2>/dev/null
                fi

                break  # 找到第一个有效目录后就退出
            fi
        done

        # 如果没有找到标准目录，尝试在源码目录中查找头文件
        if [ \"$header_copied\" = false ]; then
            echo -e \"${YELLOW}未找到标准头文件目录，尝试在源码中查找...${NC}\"

            local src_dirs=(
                \"$module_dir/src\"
                \"$module_dir\"
            )

            for src_dir in \"${src_dirs[@]}\"; do
                if [ -d \"$src_dir\" ]; then
                    local found_headers=$(find \"$src_dir\" -maxdepth 1 -name \"*.h\" -o -name \"*.hpp\" | head -1)
                    if [ -n \"$found_headers\" ]; then
                        echo -e \"${BLUE}在 ${src_dir} 中找到头文件${NC}\"

                        local module_include_dir=\"$INCLUDE_INSTALL_DIR/$module_name\"
                        mkdir -p \"$module_include_dir\"

                        find \"$src_dir\" -maxdepth 1 -name \"*.h\" -o -name \"*.hpp\" | while read header; do
                            cp \"$header\" \"$module_include_dir/\"
                            echo \"  Copied: $(basename \"$header\")\"
                        done

                        local file_count=$(find \"$module_include_dir\" -name \"*.h\" -o -name \"*.hpp\" | wc -l)
                        echo -e \"${GREEN}✓ 已安装 ${file_count} 个头文件到 ${module_include_dir}${NC}\"
                        header_copied=true
                        break
                    fi
                fi
            done
        fi

        if [ \"$header_copied\" = true ]; then
            echo -e \"${GREEN}✓ 头文件安装完成${NC}\"

            # 创建模块的版本信息文件（可选）
            echo \"Module: $module_name\" > \"$INCLUDE_INSTALL_DIR/$module_name/version.txt\"
            echo \"Installed: $(date)\" >> \"$INCLUDE_INSTALL_DIR/$module_name/version.txt\"
            echo \"Library: $so_filename\" >> \"$INCLUDE_INSTALL_DIR/$module_name/version.txt\"
        else
            echo -e \"${YELLOW}警告: 未找到任何头文件${NC}\"
        fi

        # 显示最终的目录结构
        echo -e \"\\n${BLUE}安装目录结构:${NC}\"
        echo \"库文件目录 ($INSTALL_DIR):\"
        ls -lh \"$INSTALL_DIR\" | grep \"$module_name\"
        echo \"头文件目录 ($INCLUDE_INSTALL_DIR/$module_name):\"
        if [ -d \"$INCLUDE_INSTALL_DIR/$module_name\" ]; then
            ls -lh \"$INCLUDE_INSTALL_DIR/$module_name\"
        fi

        # 可选：运行ldconfig更新缓存（需要sudo）
        if [ \"$(id -u)\" = \"0\" ]; then
            ldconfig
            echo -e \"${GREEN}已更新动态链接器缓存${NC}\"
        else
            echo -e \"${YELLOW}提示: 如需更新系统缓存，请运行: sudo ldconfig${NC}\"
        fi
    else
        echo -e \"${RED}✗ 安装失败${NC}\"
        return 1
    fi

    return 0
}

# 编译并安装单个模块
process_module() {
    local module_dir=\"$1\"

    # 编译
    build_module \"$module_dir\"
    if [ $? -ne 0 ]; then
        return 1
    fi

    # 安装
    install_library \"$module_dir\"
    return $?
}

# 查找所有模块
find_all_modules() {
    local root_dir=\"$1\"

    # 查找包含CMakeLists.txt且add_library的目录
    find \"$root_dir\" -maxdepth 2 -name \"CMakeLists.txt\" | while read cmake_file; do
        dir=$(dirname \"$cmake_file\")
        # 检查是否包含SHARED或add_library
        if grep -q \"add_library.*SHARED\" \"$cmake_file\" 2>/dev/null; then
            echo \"$dir\"
        fi
    done
}

# 主函数
main() {
    # 解析命令行参数
    BUILD_ALL=false
    CLEAN_BUILD=false
    MODULE_NAME=\"\"
    BUILD_DIR=\"\"

    while [[ $# -gt 0 ]]; do
        case $1 in
            -h|--help)
                show_help
                exit 0
                ;;
            -a|--all)
                BUILD_ALL=true
                shift
                ;;
            -c|--clean)
                CLEAN_BUILD=true
                shift
                ;;
            -b|--build-dir)
                BUILD_DIR=\"$2\"
                shift 2
                ;;
            -m|--module)
                MODULE_NAME=\"$2\"
                shift 2
                ;;
            -*)
                echo -e \"${RED}错误: 未知选项 $1${NC}\"
                show_help
                exit 1
                ;;
            *)
                # 如果还有参数，当作模块名
                if [ -z \"$MODULE_NAME\" ]; then
                    MODULE_NAME=\"$1\"
                else
                    echo -e \"${RED}错误: 多余的参数 $1${NC}\"
                    show_help
                    exit 1
                fi
                shift
                ;;
        esac
    done

    # 创建安装目录
    create_install_dir

    echo -e \"${GREEN}========================================${NC}\"
    echo -e \"${GREEN}自动编译安装脚本${NC}\"
    echo -e \"${GREEN}========================================${NC}\"
    echo -e \"${BLUE}安装目录: ${INSTALL_DIR}${NC}\"
    echo -e \"${BLUE}当前目录: ${CURRENT_DIR}${NC}\"

    # 查找CMakeLists.txt所在位置
    CMAKE_DIR=$(find_cmakelists \"$CURRENT_DIR\")

    if [ \"$BUILD_ALL\" = true ]; then
        # 编译所有模块
        echo -e \"${BLUE}模式: 编译所有模块${NC}\"

        if [ -z \"$CMAKE_DIR\" ]; then
            echo -e \"${RED}错误: 找不到CMakeLists.txt${NC}\"
            exit 1
        fi

        # 查找所有模块
        modules=$(find_all_modules \"$CMAKE_DIR\")

        if [ -z \"$modules\" ]; then
            echo -e \"${YELLOW}警告: 未找到任何模块${NC}\"
            exit 0
        fi

        success_count=0
        fail_count=0

        for module in $modules; do
            echo -e \"\\n${BLUE}处理模块: ${module}${NC}\"
            if process_module \"$module\"; then
                ((success_count++))
            else
                ((fail_count++))
            fi
        done

        echo -e \"\\n${GREEN}========================================${NC}\"
        echo -e \"${GREEN}编译安装完成: ${success_count} 成功, ${fail_count} 失败${NC}\"

    else
        # 编译单个模块（当前目录）
        echo -e \"${BLUE}模式: 编译当前模块${NC}\"

        if [ -z \"$CMAKE_DIR\" ]; then
            echo -e \"${RED}错误: 当前目录不在CMake项目中${NC}\"
            exit 1
        fi

        process_module \"$CMAKE_DIR\"
    fi

    echo -e \"\\n${GREEN}库文件已安装到: ${INSTALL_DIR}${NC}\"
    echo -e \"${YELLOW}如需使用这些库，请在CMakeLists.txt中添加:${NC}\"
    echo \"  link_directories(${INSTALL_DIR})\"
    echo \"  或设置环境变量: export LD_LIBRARY_PATH=${INSTALL_DIR}:\\$LD_LIBRARY_PATH\"
}

# 运行主函数
main \"$@\"
", "url": "https://devvv.cn/blog/cmake-multi-module-project-configuration", "title": "CMake 多模块项目配置", "summary": "CMake 多模块项目配置", "date_modified": "2026-03-02T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "CMake", "c++" ] }, { "id": "https://devvv.cn/blog/android-studio-proxy-setting", "content_html": "

取消代理​

\n

Settings -> Appearance & Behavior -> System Settings -> HTTP Proxy -> No Proxy

\n

已经通过上述设置取消了代理，但是还是走的代理：

\n

\"no_proxy.png\"

\n

打开 GRADLE_USER_HOME/gradle.properties 文件，将代理设置取消：

\n

GRADLE_USER_HOME 路径：

\n

\"gradle_user_home.png\"

\n

\"全局配置文件\"

\n

找到并删除：

\n
gradle.propertiesproperties
systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPassword=
systemProp.http.proxyPort=10810
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPassword=
systemProp.https.proxyPort=10810
\n

删除后，重启 Android Studio，问题解决。

", "url": "https://devvv.cn/blog/android-studio-proxy-setting", "title": "Android Studio 设置代理后，再取消，仍然走代理的解决方法", "summary": "Android Studio 设置代理后，再取消，仍然走代理的解决方法", "date_modified": "2026-02-28T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Android", "Android Studio", "Proxy", "代理" ] }, { "id": "https://devvv.cn/blog/android-studio-download-record", "content_html": "

windows：

\n

https://dl.google.com/dl/android/studio/ide-zips/2022.3.1.20/android-studio-2022.3.1.20-windows.zip

\n

https://dl.google.com/dl/android/studio/ide-zips/2024.3.2.15/android-studio-2024.3.2.15-windows.zip

\n

https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2025.1.2.11/android-studio-2025.1.2.11-windows.zip

\n

https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2025.3.2.6/android-studio-panda2-windows.zip

\n

linux：

\n

https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2025.1.2.11/android-studio-2025.1.2.11-linux.tar.gz

\n

https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2025.3.2.6/android-studio-panda2-linux.tar.gz

\n

历史版本归档：

\n

https://developer.android.google.cn/studio/archive

", "url": "https://devvv.cn/blog/android-studio-download-record", "title": "android studio 下载记录", "summary": "Android Studio 下载的记录", "date_modified": "2026-02-25T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "Android", "Android Studio" ] }, { "id": "https://devvv.cn/blog/testBlog", "content_html": "

这些属性是 Docusaurus 博客文章的 Front Matter（前置元数据），用于定义文章的元信息和控制页面行为。下面是每个属性的作用及常见扩展属性。

\n
\n

已给出属性的作用​

\n
属性作用
slug自定义文章 URL 路径（默认为文件名）。例如 slug: /my-post 则文章访问地址为 /my-post。
title文章标题，显示在页面和列表中。
date文章发布日期，格式通常为 YYYY-MM-DD，影响排序和归档。
authors作者，可以是字符串（作者名）或对象数组（包含 name, title, url, imageURL 等）。
tags文章标签，用于分类和筛选。可以是字符串数组或标签对象数组。
keywordsSEO 关键词，放入 <meta> 标签。
description文章描述，用于 SEO 和列表摘要。
image文章封面图 URL，用于社交媒体分享卡片。
draft草稿状态。设为 true 时文章不会出现在生产构建中，仅在开发模式可见。
\n
\n

其他常用 Front Matter 属性​

\n

1. 页面行为控制​

\n
属性说明
hide_table_of_contents隐藏右侧目录（TOC），默认 false。
toc_min_heading_levelTOC 最小标题级别（如 2）。
toc_max_heading_levelTOC 最大标题级别（如 3）。
sidebar_label侧边栏显示的自定义标签（仅文档）。
sidebar_position侧边栏排序位置（数字，仅文档）。
\n

2. 博客相关​

\n
属性说明
sticky置顶优先级（数字越大越靠前），需配合自定义插件实现。
unlisted设为 true 后文章不出现在博客列表，但可通过直接链接访问（Docusaurus 2.4+）。
hide_comment控制是否隐藏评论组件（需要自定义）。
\n

3. 搜索与 SEO​

\n
属性说明
keywords同上，支持字符串数组。
image社交卡片图片。
\n

4. 文档专用（如果使用 docs）​

\n
属性说明
id文档唯一标识（默认文件名）。
sidebar_position侧边栏位置。
sidebar_label侧边栏显示标题。
\n

5. 自定义字段​

\n

你可以添加任意自定义字段，并在主题组件中通过 frontMatter 获取。

\n
\n

示例​

\n
---
slug: /my-awesome-post
title: 我的第一篇博客
date: 2025-01-01
authors:
  - name: 张三
    title: 全栈开发者
    url: https://example.com
    imageURL: /img/avatar.png
tags: [技术, 前端]
keywords: [JavaScript, React]
description: 这是一篇关于前端技术的文章。
image: /img/cover.png
draft: false
hide_table_of_contents: false
toc_min_heading_level: 2
toc_max_heading_level: 3
sticky: 1
---
yaml
\n

这些属性可以灵活组合，满足大多数博客和文档站点的需求。

", "url": "https://devvv.cn/blog/testBlog", "title": "这是一篇测试文章", "summary": "这篇文章是测试", "date_modified": "2025-12-31T00:00:00.000Z", "author": { "name": "vv", "url": "https://devvv.cn" }, "tags": [ "测试" ] } ] }