# Blog **Repository Path**: tomoo996/blog ## Basic Information - **Project Name**: Blog - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-14 - **Last Updated**: 2026-09-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VOID.LOG 一个极简、极客科技风的全栈博客。前端使用 **React 19 + TypeScript + Vite + React Router**，后端使用 **Go + Gin + SQLite**。深色底、荧光绿点缀、等宽字体与几何线框封面，支持八套全站颜色主题和手机布局。 [快速上手](#快速上手) · [功能概览](#已实现) · [文档索引](#文档索引) · [生产部署](#生产构建) · [数据与备份](#数据与定制) · [运行排障](docs/architecture/operations.md) ## 快速上手 使用 **Go 1.26.2+、Node.js 22.18+ 和 npm**；Windows 一键启动另需 **PowerShell 7+**。命令应可从 PATH 找到，首次安装依赖需要联网。以下开发命令均从仓库根目录执行。 | 运行方式 | 适用场景 | 入口 | | ---------------- | ----------------------------------------------- | ----------------------------------- | | Windows 一键启动 | 由脚本构建、后台启动并登记两个开发进程 | [启动与停止脚本](#windows-一键启动) | | 手动开发 | Linux、macOS、Windows，或需要分别查看前后端日志 | [两个终端分别启动](#手动开发跨平台) | | 生产运行 | 构建前端后由 Go 同时提供页面与 API | [生产构建与运行](#生产构建) | ### Windows 一键启动 在项目根目录执行： ```powershell pwsh -File scripts/start.ps1 ``` 脚本安装缺少的前端依赖、构建 Go 后端，然后在后台启动 Go 与 Vite。日志和进程登记位于 `output/runtime/`。再次执行会重启本项目登记的开发进程；脚本按 PID、启动时间和程序路径核对身份，其他程序占用端口时直接报错。 停止由脚本启动的开发服务： ```powershell pwsh -File scripts/stop.ps1 ``` 停止脚本保留数据库，只处理身份匹配的登记进程；IDE、手动启动和生产服务需通过各自的运行入口停止。 可选初始化方式： ```powershell pwsh -File scripts/start.ps1 -Preview # 跳过首次管理员创建 pwsh -File scripts/start.ps1 -GenerateAdmin # 按下述条件生成随机初始密码 ``` `-Preview` 仅跳过首次管理员创建；已有账户仍可登录管理，数据库仍执行迁移。关闭预览后正常启动，会在尚无管理员时创建首个账户。 `-GenerateAdmin` 在数据库没有管理员且未提供 `ADMIN_PASSWORD` 时生成随机密码，写入 `output/runtime/initial-admin.txt`。若已提供 `ADMIN_PASSWORD`，则使用环境密码初始化。已有账户不会重置，也不会因此重新生成密码文件。随机凭据文件不提交版本库，保存好密码后可删除。详细脚本说明见 [scripts/README.md](scripts/README.md)。 ### 手动开发（跨平台） 终端一启动 Go API： ```sh go -C server run ./cmd/blog ``` 终端二安装前端依赖并启动 Vite： ```sh npm --prefix web ci npm --prefix web run dev ``` 首次启动或锁文件变更后执行 `npm --prefix web ci`；日常开发依赖未变时可直接执行 `npm --prefix web run dev`。两个进程分别占用当前终端，停止时在各自终端按 `Ctrl+C`。 Vite 默认访问地址为 `http://localhost:5173`，将 `/api` 代理到 `http://127.0.0.1:8080`。`go -C server` 会将 Go 工作目录切到 `server/`，因此默认数据库和静态目录分别落在仓库的 `data/` 与 `web/dist/`。IDE 或其他启动方式需核对工作目录，详见[配置与路径说明](docs/architecture/operations.md#2-三种启动方式的差别)。 ### 访问与首次登录 | 入口 | 默认地址 | 用途 | | ------------ | ---------------------------------- | ------------------------------------------------------- | | 博客 | | 查看文章、笔记、专栏与小工具 | | 管理后台 | | 登录后管理内容、媒体与站点设置 | | API 健康检查 | | 检查 API 和数据库连接；成功不代表所有写入与交互都已验证 | 首次正常启动且库中没有管理员时，默认创建 `admin / 123456`。首次启动前也可在**后端进程环境**提供 `ADMIN_USERNAME` 和 `ADMIN_PASSWORD`，自定义密码需 12–72 UTF-8 字节。登录后点击顶部用户名进入「个人信息」修改密码；密码以 bcrypt 哈希保存，已有账户不会被重启或新的初始化环境值覆盖。 手动启动使用 `BLOG_PREVIEW=true` 可跳过首次账号创建；它与脚本 `-Preview` 一样，不停用已有账号，也不将数据库变成只读。应用不自动读取 `.env` 文件，[server/.env.example](server/.env.example) 仅用于说明配置；完整参数和 API 见 [server/README.md](server/README.md)。 ## 已实现 | 能力 | 内容与使用入口 | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | 内容阅读 | 文章、树形笔记、专栏、搜索、收藏、评论和 RSS；详见[文章阅读](#文章阅读与代码展示)、[笔记](#笔记)、[专栏与订阅](#评论专栏与订阅)。 | | 写作与管理 | Markdown 编辑、文章恢复副本、媒体库、内容检查、批量操作和站点设置；详见[媒体与恢复](#媒体库与写作恢复)、[内容检查](#内容检查)。 | | 部署配置生成 | 系统初始化、Docker run、Dockerfile、Compose、K8s 单/多应用及 Helm，支持场景预设、手动稿、模板和下载；详见[小工具指南](docs/tools.md)。 | | 导入与分发 | 文件或语雀导入、语雀私密文档、DEV.to 草稿、Markdown/HTML 和离线资料包；详见[导入与分发](#内容导入与分发)。 | | 主题与性能 | 八套全站主题、固定深色代码高亮、四档动画性能、按需 WebGL、手机布局和 200 款封面；详见[性能指南](docs/performance.md)。 | | 存储与身份 | SQLite 持久化、自动迁移、管理员会话、CSRF 与来源校验；数据保存范围见[数据与备份](#数据与定制)。 |
展开完整功能清单与交互细节 - **博客前台**：精选文章、分页、全文搜索、标签筛选、本地收藏、关于页、404 页面；归档按年月展示，支持搜索、标签筛选与年份跳转。 - **阅读体验**：Markdown / GFM、手机与桌面目录、章节链接复制、正文阅读进度、本地继续阅读、三档字号与专注模式；代码支持多语言高亮、换行、长块展开及完整复制。正文图片可点击放大，支持 Escape 关闭并返回原焦点。 - **评论与交流**：文章下匿名留言、审核后公开、作者回复；后台按状态筛选、搜索、分页与删除。提交失败保留内容，响应丢失后重试不会重复创建评论。 - **专栏合集**：后台选择文章并调整顺序，设置简介、封面与公开状态；前台支持专栏搜索、四种排序、目录内查找与上下篇连续阅读，筛选地址可收藏和分享。草稿自动隐藏，删除专栏保留文章。 - **专栏阅读清单**：手动标记已读、查看进度与剩余时长、继续第一篇未读，支持按阅读状态筛选；目录与文章内专栏导航同步，内容更新后提示重读。后台可按发布状态筛选文章、批量加入目录、移至首篇或末篇。 - **RSS 订阅**：订阅说明页、一键复制地址、RSS 2.0 输出最近 20 篇公开文章摘要。 - **交互与动效**：卡片滚动入场、按钮悬停与按压反馈、加载骨架和弹窗进退场；收藏显示操作提示，目录跟随阅读高亮。支持 Ctrl/⌘+K 搜索、手机导航与弹窗焦点归还、后台方向键切换标签；动效遵循全局动画性能档位和系统减少动态效果设置。 - **统一下拉选择**：前台排序、归档标签和后台筛选使用 Radix Select，提供主题化选项面板、选中标记、键盘导航、浮层避让与长列表滚动。 - **Three.js 三维装置**：首页模块化数据核心、专栏知识星图，包含轨道粒子与线框结构；鼠标拖动或方向键旋转、点击／Enter 发出脉冲、展开结构、重置视角。适配明暗主题和手机，可见时按需绘制，交互结束后停止调度，离屏或标签页隐藏后立即停帧；不支持 WebGL 时保留线框插画。 - **整站动效**：全局轨道、信号线路、光晕和星点静态呈现；保留页面切换、首页入场、卡片聚光、按钮波纹，以及后台目录展开、选择、表单焦点和统计数字反馈。封面仅在桌面悬停或键盘聚焦时播放一次；手机降低装饰密度，标签页隐藏时暂停动画，并遵循系统的减少动态效果偏好。装饰不拦截点击，也不移动表单或固定工具的祖先容器。 - **全局动画性能**：顶部仪表盘按钮选择最高／均衡／省电／关闭，首次默认最高，前台与后台共用并保存在当前浏览器，同源标签页同步。最高保留完整交互和清晰三维画面；均衡降低渲染预算；省电精简背景、封面、数值入场和鼠标效果；关闭动画与过渡，保留功能操作。所有档位继续在空闲、离屏和后台停帧，系统减少动态效果优先使用静态呈现。 - **小工具**：`/tools` 提供 Docker run、Dockerfile、Compose、Kubernetes 单应用及多应用、Helm Chart 和 Linux 系统初始化脚本生成。系统初始化提供 99 项软件、12 套可叠加软件组合，并支持搜索、分类和已选筛选；可配置网络参数、切换系统软件源，并生成独立连通性/下载/iperf3 测速脚本。左右工作台实时校验，结构树预览、彩色代码、复制和下载；K8s 支持 12 种资源类型，每套应用独立输出，Helm 支持完整 `.tgz` 下载。集成渡渡鸟公共 API 的镜像搜索与同步查询，选用源地址/镜像地址后回填当前配置。生成内容仅在浏览器中处理，查询按需发送；详见 [小工具说明](docs/tools.md)。 - **管理总览**：文章、笔记、专栏的总量和公开/私密分布，最近 6 条文章与笔记更新，草稿、待审评论和媒体入口；支持刷新及近 3/6 个月文章发布趋势。`GET /api/admin/dashboard` 使用只读事务汇总元数据，不加载文章正文。阅读是现存文章的累计请求次数（含撤回草稿），非独立访客；标签仅统计文章。桌面和手机顶部持续可见，保留当前位置、新建资源及主题/账户操作。 - **大型视觉场景**：首页和专栏提供大幅信号流背景与三维装置，支持浏览器原生全屏沉浸浏览，复用同一画布按需绘制；不支持原生全屏时仍可在页内操作。画布与交互帧率按全局动画性能档位限制，最高档桌面 60 FPS、手机 30 FPS；空闲、离屏与后台停止连续绘制。无法使用 WebGL 或缺少可视性 API 时保留静态图。笔记页采用紧凑的树形阅读布局。 - **动画封面库**：共 200 款：保留 4 款经典封面，以 49 个开发、运维、网络、计算机和算法主题衍生 196 款动画封面；统一经典分层、终端、代码与网格风格。文章和专栏共用分类、搜索、分页，支持主题适配，桌面悬停或键盘聚焦时播放一次，离屏暂停；封面随文章保存并支持本地草稿恢复。程序化封面不作为图片分发到第三方平台。 - **独立文章保存**：只填写标题与正文即可保存，每篇文章分配独立记录和自动地址；同名文章可以并存，后续编辑按编号更新并保持原链接。已有公开链接与导入路径保持兼容。 - **管理后台**：管理员登录、真实统计、近六个月发布记录与阅读排行；文章搜索、排序、默认每页 50 篇，可自定义 1–100 篇；批量发布／移回草稿／删除，手机端卡片列表。支持确认后发布全部草稿，包含其他分页和筛选之外的内容，分批显示进度，失败后刷新列表并可重试。提供 Markdown 分屏编辑、草稿与精选；未保存内容离开时提示。 - **内容检查**：支持文章、笔记及联合检查，检查标签、图片说明、代码语言和站内文章／笔记链接，文章额外检查摘要；支持分批扫描、搜索、状态筛选、直接编辑及 JSON 报告导出。 - **媒体库**：PNG/JPEG 批量上传、搜索、图片描述、复制地址与 Markdown；重复图片复用，已被文章引用的图片禁止删除，编辑器可直接选择插图。 - **写作辅助**：本地恢复副本、显式恢复或丢弃、Markdown 工具栏与 Ctrl/⌘+S 保存；保存会保留文章当前的草稿／发布状态，登录过期时保留输入。 - **站点设置**：后台修改名称、标语、站点简介、作者资料和 GitHub 链接，实时预览页面及搜索摘要；支持 Ctrl/⌘+S、离开保护、登录恢复后保存和常用站点地址复制。修改密码需验证旧密码，成功后所有设备重新登录。 - **导入与分发**：Markdown/TXT/ZIP 与语雀知识库导入，预览纠错、筛选、批量选择与失败重试；分发为语雀私密文档、DEV.to 草稿，提供图片预检、Markdown/HTML 预览与复制、带本站图片的离线 ZIP 和操作记录。 - **全站主题**：顶部调色板统一切换深色、浅色、暖纸、森林、海蓝、暮紫、纯黑和纯白，前台与后台共用；黑白主题的程序化图形使用灰阶，上传图片保留原色；正文与阅读界面跟随全站主题，代码块始终保留固定深色底和彩色高亮。选择保存在当前浏览器，跨标签页同步，兼容原有明暗偏好。 - **持久化与认证**：SQLite 自动迁移、bcrypt 密码哈希、24 小时 HttpOnly Cookie 会话、CSRF 与来源校验、登录限流。 - 首次初始化包含 **7 篇公开文章 + 1 篇草稿**。仅播种一次，重启不会覆盖你的编辑。
## 目录 ```text web/src/app/ 路由、Provider、布局和样式入口 web/src/pages/{public,admin}/ 按业务划分的公开与管理页面 web/src/features/ 各业务的请求、类型、状态、模型和界面 web/src/shared/ 会话、请求、Markdown、通用UI和视觉组件 server/internal/app/ 应用组装与资源生命周期 server/internal/transport/ 按业务分组的HTTP处理 server/internal/application/ 业务用例 server/internal/domain/ 数据契约 server/internal/persistence/ SQLite连接、迁移与业务存储 server/internal/integrations/ 语雀和DEV.to平台协议 scripts/dev/ 开发服务控制和运行时辅助函数 scripts/architecture/ 仓库结构与依赖规则 docs/ 架构、功能、性能与运行文档，详见下方索引 data/、output/ 运行数据和生成产物，忽略提交 ``` 项目维护与贡献约定见 [AGENTS.md](AGENTS.md)。各专题文档的内容和查阅场景见下方索引。 ## 文档索引 先按问题选择入口，再按分类查阅完整文档。下方三个分类覆盖 `docs/` 及子目录中的全部文档，文件名相对于 `docs/`。 ### 按问题快速查找 | 当前需求或问题 | 直接查阅 | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 启动报 `readonly database`，或不确定实际数据库路径 | [配置生效方式](docs/architecture/operations.md#1-配置何时读取)、[只读数据库定位](docs/architecture/operations.md#4-只读数据库启动错误怎样定位) | | 登录失败、保存遇到 401/403，或更改密码后需要重新登录 | [浏览器认证排查](docs/architecture/operations.md#5-浏览器认证排查顺序)、[文章保存与身份校验](docs/architecture/flows.md#1-登录与文章保存) | | 生成 Dockerfile、复杂 Helm Chart，或保存自己的配置模板 | [多阶段构建](docs/tools.md#dockerfile-多阶段构建)、[复杂 Chart](docs/tools.md#helm-复杂应用-chart)、[我的模板](docs/tools.md#我的模板) | | 生成 Linux 初始化脚本、选择软件和自定义优化 | [系统初始化](docs/tools.md#linux-系统初始化)，支持 Ubuntu / Debian / Rocky Linux / AlmaLinux | | 修改表单后手动稿没更新，或刷新后找不到模板 | [手动稿与生成结果](docs/architecture/flows.md#3-生成工具手动编辑和模板)、[本地数据排查](docs/architecture/operations.md#6-静态页面生成器和本地数据排查) | | GPU 占用高、页面加载慢，或需要确认优化效果 | [加载与交互机制](docs/performance.md#前端加载与交互)、[性能复测](docs/performance.md#复测) | | 准备修改一个功能、表字段或删除策略 | [维护文件地图](docs/architecture/file-map.md)、[数据关系与约束](docs/architecture/data-model.md) | | 修改完成后，需要确认该执行哪些检查 | [构建、静态检查与手动验收](docs/architecture/checks.md) | ### 架构与业务 | 文档 | 用途与查阅场景 | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [architecture.md](docs/architecture.md) | **架构总览**：系统关系、目录、依赖方向、运行方式和数据归属。首次接手项目时从这里开始。 | | [architecture/frontend.md](docs/architecture/frontend.md) | **前端结构**：路由、业务模块、状态、阅读器、生成器、模板、主题和样式。开发界面或查找前端职责时阅读。 | | [architecture/backend.md](docs/architecture/backend.md) | **后端结构**：Go 分层、依赖装配、认证、事务、导入分发、媒体和资源生命周期。修改 API 或服务端用例时阅读。 | | [architecture/flows.md](docs/architecture/flows.md) | **业务流程**：保存、公开、生成、模板和导出的时序、状态变化与失败恢复。追踪一次操作的提交或并发边界时阅读。 | | [architecture/data-model.md](docs/architecture/data-model.md) | **数据模型**：表字段、外键图、索引、校验、删除联动、幂等和迁移。调整存储结构或查询时阅读。 | | [architecture/file-map.md](docs/architecture/file-map.md) | **维护地图**：按功能列出源码入口、关联文件和核查点。明确要改什么后，用它定位文件。 | | [architecture/analysis.md](docs/architecture/analysis.md) | **架构分析**：当前结构的收益、成本、限制和演进建议。评审方案或规划重构时阅读。 | ### 使用、运行与验收 | 文档 | 用途与查阅场景 | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | [tools.md](docs/tools.md) | **小工具指南**：七类生成器、场景预设、参数限制、手动编辑、本地模板、下载和镜像查询。使用或扩展生成能力时阅读。 | | [architecture/operations.md](docs/architecture/operations.md) | **运行排障**：环境变量、启动、健康检查、数据库权限、认证、静态资源与本地数据。启动或实际操作异常时查阅。 | | [performance.md](docs/performance.md) | **性能指南**：加载、动画预算、预览、压缩传输和 SQLite 查询机制，以及历史测量和复测方法。分析性能问题时查阅。 | | [architecture/checks.md](docs/architecture/checks.md) | **验收指南**：当前可运行的构建、格式、边界和静态检查，以及浏览器手动验收范围。修改完成后据此选择检查。 | ### 历史迁移记录 | 文档 | 用途与查阅场景 | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [architecture/migration.md](docs/architecture/migration.md) | **目录迁移说明**：源码目录改造的顺序、兼容约束、完成条件与旧进程切换方式。追溯目录调整时阅读；不是数据库版本迁移手册。 | | [architecture/implementation.md](docs/architecture/implementation.md) | **历史实施记录**：2026-09-15 目录改造的范围、保留行为与当时验收结果。核对改造背景和历史依据时阅读。 | 首次理解项目可按“架构总览 → 前端或后端结构 → 业务流程”阅读；实际改功能可按“维护地图 → 对应专题 → 验收指南”查阅。历史记录中的测试数量、旧目录和性能测量仅对应记录时的状态，当前检查入口以验收指南为准。 新增、移动或删除 `docs/` 文档时，同步更新上述分类、用途及问题入口；调整章节标题时也要检查直达链接。 ## 验证命令 ```sh npm --prefix web run build # TypeScript 检查及生产构建 npm --prefix web run lint # ESLint npm --prefix web run format:check # Prettier npm --prefix web run check:boundaries # 分层、循环、大小写与公开入口 go -C server build ./... # Go 包编译 go -C server vet ./... # Go 静态检查 node scripts/check-architecture.mjs # Go依赖层、目录布局和文档链接 ``` 2026-09-19 已按要求移除自动化测试代码及运行入口，当前验证使用上述构建与静态检查，并按[验收指南](docs/architecture/checks.md)手动检查受影响流程。前端修改后使用 `npm --prefix web run format` 格式化，Go 使用 `gofmt`。桌面/手机布局、真实点击与剪贴板需在浏览器中验收；截图在本地 `output/playwright/`，不进入版本库。 ## 生产构建 先在仓库根目录构建前后端： ```sh npm --prefix web ci npm --prefix web run build go -C server build -o ../bin/voidlog ./cmd/blog ``` 运行前，在 Go **进程环境**中设置实际部署参数。应用不会自动加载 `.env`： | 配置 | 生产运行时的含义 | | -------------------- | ----------------------------------------------------------------------------- | | `BLOG_ORIGIN` | 实际浏览器来源，例如 `https://blog.example.com`；用于写请求校验及公开链接生成 | | `BLOG_ADDR` | Go 监听地址，默认 `127.0.0.1:8080`；与反向代理的上游保持一致 | | `BLOG_SECURE_COOKIE` | HTTPS 主来源默认启用；经 HTTPS 反向代理访问时保持启用 | | `BLOG_DB` | 实际数据库路径；使用服务管理器或改变工作目录时，显式配置绝对路径 | | `BLOG_STATIC_DIR` | 完整前端构建目录；包含 `index.html`、分块和预压缩文件，不能只部署入口文件 | 沿用仓库布局时，从 `server/` 目录启动二进制： ```sh cd server ../bin/voidlog ``` Windows 构建输出名可改为 `../bin/voidlog.exe`，从 `server/` 执行 `../bin/voidlog.exe`。若改用其他工作目录，先设置 `BLOG_DB` 和 `BLOG_STATIC_DIR` 的绝对路径，避免打开另一份数据库。 Go 同时提供 API、静态页面和前端路由，生产运行无需另启 Vite。更新前端后重新构建并部署完整 `web/dist/`；更新 Go 后重新构建并重启对应服务。Windows 开发脚本固定使用本地端口和开发 Cookie 配置，不用于生产部署。配置限制与故障定位见[运行指南](docs/architecture/operations.md)。 ## 数据与定制 ### 数据保存在哪里 | 数据 | 保存位置 | 保留与备份方式 | | ------------------------------------------------------------ | -------------------------------- | -------------------------------------------------------------------------- | | 文章、笔记、专栏、评论、站点设置、账号、会话及导入分发记录 | `BLOG_DB` 指定的 SQLite 数据库 | 随数据库持久化，重启后保留 | | 媒体库上传的图片 | 同一数据库中的图片 BLOB 与元数据 | 随数据库一起备份，不是独立上传目录 | | 主题、动画档位、阅读记录、收藏、文章恢复副本、已保存工具模板 | 当前浏览器的本站 localStorage | 不包含在数据库备份中，也不自动跨设备同步；清除站点数据会移除这些副本和偏好 | | 尚未保存的生成器配置和手动稿 | 当前工具工作区内存 | 刷新后需通过显式保存的模板恢复；重要输出可先下载文件 | | 构建产物 | `web/dist/`、`bin/` | 可由源码重新构建，不等同于业务内容备份 | | 开发日志与进程登记 | `output/runtime/` | 用于运行管理和排障，历史日志不会由构建恢复 | `output/runtime/initial-admin.txt` 是首次生成的凭据文件，按上方初始化说明保存或清理；重新构建或对已有账号运行 `-GenerateAdmin` 不会恢复该文件中的原始密码。 按上方 `go -C server run ./cmd/blog` 或 Windows 脚本启动时，默认数据库位于仓库 `data/blog.db`。程序自身使用 `../data/blog.db`，相对于 **Go 进程工作目录** 解析；备份前应确认实际路径。 ### 备份前确认 离线备份前，停止所有访问该库的进程并等待退出；Windows 停止脚本只处理登记的开发进程，IDE、手动启动或生产服务需分别停止。SQLite 使用 WAL，在线备份应通过 SQLite 备份机制取得一致快照，不直接将运行中的主 `.db` 文件视为完整备份。具体边界见[数据库与 WAL 说明](docs/architecture/operations.md#4-只读数据库启动错误怎样定位)。 单篇文章的离线 ZIP 用于阅读和内容转移，不包含整个数据库、账号或浏览器模板。备份数据库也不会保存浏览器中的本地恢复稿或工具模板；需要保留的内容应另外保存。 ### 站点与个人设置 字体文件随构建提供，页面无外部字体服务依赖。几何封面由 SVG/CSS 绘制，不需要远程图片。 登录后台后，在 **站点设置** 修改名称、介绍、作者信息和 GitHub 链接，无需改代码。设置保存在 SQLite，重启后保留。颜色可通过顶部调色板切换并保存在当前浏览器；定制色板见 [palettes.css](web/src/shared/theme/palettes.css)，主题选项与背景元数据见 [catalog.ts](web/src/shared/theme/catalog.ts)。文章管理支持勾选本页批量操作，切换筛选或页面会清空选择，删除前需确认。 点击后台顶部用户名进入 **个人信息**（`/admin/profile`）可修改密码；站点设置底部也保留改密入口，在该页需先保存或撤销站点信息修改。输入旧密码与新密码，修改成功后全部旧会话失效，需使用新密码重新登录。没有通过邮件找回密码的功能。 站点信息支持 **Ctrl/⌘+S** 保存，必填项和 GitHub 地址先经过表单校验。登录失效时输入仍保留，可在新标签页使用原账户登录，再回来保存。搜索摘要预览展示首页标题和简介的排版，不保证搜索引擎的实际展示；主页、RSS 和专栏地址按当前访问来源生成，可直接复制。 ## 内容检查 后台 **内容检查** 可选择全部内容、文章或笔记，包含文章草稿与私密笔记。共同检查标签、图片说明、代码语言，以及失效的站内文章／笔记链接和公开内容指向草稿／私密笔记的链接；仅文章检查摘要。支持按标题、路径或标签搜索，区分公开内容、文章草稿和私密笔记，按问题类型筛选并跳转到对应编辑页。公开资源可直接阅读。 每批按最近更新时间扫描最多 **200 条资源**，通过「检查上一批／下一批」覆盖更早的内容；链接目标始终依据完整文章和笔记索引判断。批内每页展示 10 条结果，搜索、统计和 JSON 导出均仅针对当前批次；报告包含资源类型与批次范围。接口为 `GET /api/admin/content-check?kind=all|post|note&scanPage=1`，无参数时保留旧版文章检查响应。 检查只读取已保存内容，不修改正文或公开状态；解析 Markdown，不请求外部站点，不检查章节锚点或原始 HTML。重新检查失败会保留当前范围的上次报告，切换类型或批次时重新读取，登录失效后清除报告。更新后需重新运行 Go 后端以加载新接口行为。 ## 文章阅读与代码展示 在 Markdown 代码围栏的三个反引号后填写语言，例如 `go`、`tsx`、`python`、`bash`、`json`、`sql`、`html` 或 `yaml`。阅读页与后台预览使用 [rehype-highlight](https://github.com/rehypejs/rehype-highlight) 高亮；未声明或不支持的语言保留为纯文本。代码始终使用独立的深色底和彩色语法高亮，不受全站主题切换影响；工具栏显示语言、行数，提供 12–20px 独立字号（默认 15px）、换行和完整复制。不换行时显示同步行号，换行时隐藏行号，复制不包含行号；超过 18 行可滚动查看或展开全部。 文章与笔记正文、阅读工具及图片查看器统一跟随顶部全站主题切换；阅读设置只保留排版选项。代码块固定深色底和彩色高亮，切换主题时保持不变。阅读工具栏支持章节目录、16/18/20 三档字号和专注模式。阅读位置只保存在当前浏览器，保留最近 30 篇、90 天内的未读完文章；再次打开可选择继续或从头阅读。正文修改后不恢复旧版本的位置。通过章节链接打开时直接定位章节。 ## 内容导入与分发 在后台侧栏打开 **导入与分发**： 1. **内容导入**：先选择「文章」或「笔记」，再上传 Markdown、TXT 或 ZIP，或填写语雀 `owner/book` 与访问令牌。先读取预览，再选择文档导入。文件候选可修改标题与标签，文章还可修改路径、摘要；支持搜索、状态筛选、选择当前筛选和仅选失败项。相同正文候选合并并保留首次元信息。每批最多 20 篇、上传 6 MiB、解压总量 5 MiB、单篇文章 512 KiB；笔记标题最多 120 字符、正文 64 KiB、标签 8 个，超限须调整，不会截断。语雀每批最多导入 10 篇，列表仅展示前 20 篇，正文在提交时读取并校验。 2. **导入后整理**：文章保存为草稿，笔记保存为私密且不置顶。两种目标分别识别重复来源，保留已有内容；删除笔记后可重新导入。文章路径重名自动添加数字后缀。图片附件不迁移，相对图片需要补充；语雀未能返回 Markdown 的文档可先从原平台导出。Notion、Obsidian 等通过 Markdown 文件导入，不包含账号同步。 3. **多平台分发**：选择文章后先检查图片。缺失图片、无法解析的相对地址和开发环境图片不能直接在线分发；配置公共 HTTPS `BLOG_ORIGIN` 后，本站图片自动转换为完整地址。预检只检查引用、库内文件与地址格式，不探测公网可达性、防盗链或平台权限。使用具有写权限的令牌手动创建语雀私密文档或 DEV.to 未发布草稿，完成后去目标平台检查。令牌仅用于当前请求，不写入数据库或浏览器存储。 4. **辅助分发**：复制／下载 Markdown 或 HTML，再到掘金、CSDN、知乎编辑器粘贴或导入。本站提供编辑器入口，不宣称这些平台已自动发布。 5. **操作记录**：查看最近成功导入和分发／导出结果。明确失败可修正后重试；超时、响应丢失或进程中断保留「待确认／处理中」，请先检查目标平台，系统会阻止相同内容重复创建。 6. **离线资料包**：选择文章后点击「下载 ZIP」，包内包含 `index.html`、原始 `source.md`、说明与本站图片。解压后打开 HTML 阅读，本地图片无需联网；外链图片不会下载，仍依赖原地址。最多 32 张本站图片、合计 32 MiB，缺失或无法携带的相对图片须先处理。它是单篇内容导出，不是数据库备份；ZIP 导入仍不迁移附件。 导入与分发标签之间切换会保留当前预览和输入；切换文章／笔记导入目标会清空候选和结果，须重新预览，避免混用重复来源状态。离开页面时提醒未完成内容。读取或登录失败保留编辑值，可原地重试。预览、下载和发送校验文章内容版本；在其他页面保存文章后，请点击「重新检查文章」。已成功分发后修改的版本可再次提交，待确认的请求继续阻止盲目重发。 平台接口依据[语雀官方 SDK](https://github.com/yuque/sdk/blob/master/lib/doc.js)与 [Forem 官方文档](https://developers.forem.com/api/v1#tag/articles/operation/createArticle)。真实账号连通性、权限和平台排版需在获得授权后使用相应账户手动确认；静态检查不会向平台发送请求。完整请求字段与限制见 [server/README.md](server/README.md)。 ## 评论、专栏与订阅 - **专栏浏览**（`/collections`）：按标题、简介或路径搜索，按最近更新、阅读时长、文章数量或名称排序；关键词与排序保存在地址中。目录内搜索文章标题、摘要与标签，保留原章节编号；从专栏进入文章后，可继续阅读上下篇或返回目录。加载失败可重试，空专栏列表会推荐已有文章。 - **阅读清单**：在专栏目录或文章内的专栏导航手动标记已读，也可撤销。已读数、剩余分钟和「继续未读」仅按当前公开章节计算；目录可筛选已读、未读与待重读。标记按专栏、文章和文章更新时间保存，重排目录保留记录，文章修改后提示重读。记录仅存当前浏览器，最多保留最近 1,000 条标记；同源标签页同步，清理浏览器数据会移除记录，不提供跨设备同步或同时写入的事务保证。存储失败会提示，原有记录保留。 - **评论管理**（`/admin/comments`）：留言默认待审核，可通过、拒绝、恢复待审核、回复或删除。只有审核通过且文章已发布时，评论与作者回复才公开。评论为纯文本，昵称最多 40 字、正文最多 2000 字；每个来源每 15 分钟最多 5 条新留言。不收集邮箱，不保存评论者 IP。 - **专栏管理**（`/admin/collections`）：新建专栏，填写标题、英文访问路径和简介，从文章库选取内容并用上下箭头编排。每个专栏最多 100 篇，支持空专栏和未公开保存。勾选「公开专栏」后出现在 `/collections`，成员中的草稿继续隐藏。未保存离开会提示；专栏保存或回复遇到登录过期时保留输入，可在新标签页登录后重试。 - **专栏批量管理**：支持关键词与可见性筛选，默认每页 50 个，可自定义 1–100 个。勾选当前页或全部筛选结果后，可批量公开、设为私密或删除；全选仅包含当前筛选结果。翻页和切换公开／未公开筛选保留选择，修改搜索或刷新清空选择。删除不限制状态，只处理明确勾选的专栏；操作前确认数量，每批最多 100 个并显示进度，失败停止并刷新状态。删除只移除专栏和目录关联，保留文章与笔记。 - **快速编排**：候选文章支持搜索与已发布／草稿筛选，一次加入当前筛选中尚未选择的文章，按文章库顺序追加。达到 100 篇时只加入剩余名额，明确显示未加入数量；已选文章支持上移、下移、移至首篇或末篇。所有操作在点击「保存专栏」后才写入服务器。 - **RSS 订阅**（`/subscribe`）：复制 `/api/feed.xml` 的完整地址到阅读器。订阅源自动使用站点名称和简介，输出最新 20 篇公开文章的摘要与链接，读取不增加浏览量。部署时将 `BLOG_ORIGIN` 设置为实际公开域名，以生成正确链接；本地地址只适合能访问本机的阅读器。 首次启动新增模块时自动执行版本 5 迁移，只新增表与索引，不改动已有文章或管理员。专栏、评论初始为空，可直接从后台开始整理。 ## 媒体库与写作恢复 - **图片管理**（`/admin/media`）：支持 PNG/JPEG，每次最多 5 张，单张上传不超过 5 MiB、1200 万像素、任一边不超过 8192 像素。服务端重新编码并移除元数据，保留 JPEG 拍摄方向；图库最多 500 张、256 MiB，图片与信息一起保存在 SQLite 中，随数据库备份。图片链接可公开访问。 - **插图与清理**：编辑器工具栏打开媒体库，在光标或选中文字的位置插入 Markdown。名称和 Alt 描述可修改，已有文章的文字不会自动改写。引用统计涵盖已保存的草稿和公开文章；删除前会再次检查引用。未保存内容和外部平台的链接无法统计，删除图片会使这些链接失效。 - **跨平台图片**：插入的本站图片使用 `/api/media/...` 相对地址。分发预检通过且配置公共 HTTPS 来源时，分发与在线导出会自动转为完整地址；本地 `localhost` 图片不能供远程平台使用，可先下载离线资料包，或在目标平台重新上传。 - **本地恢复**：编辑时自动保存浏览器副本，按管理员和文章区分，最多 10 份、保留 7 天。重新打开后选择恢复或丢弃；恢复后仍需保存到服务器。存储不可用、配额不足或内容过大时显示提示。检测到其他标签页修改副本后暂停本标签页的本地写入，请先复制当前内容，再重新打开编辑器选择恢复；不提供跨标签页合并或原子锁。 - **快捷操作**：Ctrl/⌘+S 保存当前发布状态；正文中 Ctrl/⌘+B、Ctrl/⌘+I 添加粗体、斜体。服务器保存成功后清除本编辑器的副本；本地副本不跨设备同步，也不替代数据库备份。 媒体模块首次启动自动执行版本 6 迁移，仅新增媒体表与索引，不改动已有内容。图库初始为空。 本版本面向单管理员、单实例博客；暂未包含多用户管理和邮件订阅。后台文章列表在客户端分页，公开首页通过 API 的 page/limit 分页；评论与媒体列表由服务端分页，适合个人博客内容量。发布图按当前公开文章的首次发布时间（UTC）统计；阅读数表示文章请求次数；收藏不跨设备同步。 ## 笔记 - 前台 `/notes` 和 `/notes/:id` 采用左侧树形目录、右侧阅读区，仅展示公开笔记。目录按首个标签分组，`Go/并发` 这样的标签形成多级目录；无标签归入「未分类」。目录默认全部收起，直接打开笔记也不会自动展开其所在目录；可手动展开或全部展开，搜索时展开匹配目录。支持标题与标签搜索、当前笔记高亮、直接链接及浏览器前进后退，手机端目录可收起。 - **长文阅读**：正文默认 18px，工具栏提供 16/18/20 三档字号、标准／宽松行距和适中／宽屏两种宽度，排版偏好保存在当前浏览器。专注模式收起笔记目录与侧边章节，随时可从工具栏退出；修改排版时尽量保留当前段落或列表项的位置。 - **宽屏查看**：笔记工作区最大 1880px，标准正文最大 960px；桌面工具条可一键切换宽屏，正文铺满可用空间，专注模式最大 1680px。章节侧栏只在阅读区足够宽且有章节时出现，较窄屏幕可从工具条打开目录，避免挤压正文。 - **章节与连续阅读**：本篇目录来自正文二、三级标题，滚动时高亮当前章节并显示正文阅读进度；手机和专注模式可从工具栏打开章节。段落链接支持直接定位，保留搜索／标签条件；上一篇／下一篇按当前筛选后的目录顺序阅读，不受目录折叠影响。目录提供「定位当前笔记」，仅在当前笔记仍符合筛选时展开对应层级。长表格可横向滚动，代码继续支持换行、展开与复制。 - 目录接口 `/api/notes/index` 只返回公开笔记元信息，选择笔记后才读取正文。分组由现有标签生成；调整笔记标签并保存即可改变目录位置，不额外创建文件夹或复制笔记。 - 后台 `/admin/notes` 管理笔记。文章和笔记统一通过 `/admin/resources/new`「新建资源」创建，类型按钮只切换页内编辑器，不改变地址或侧栏选中项；未保存切换会先确认，保存期间不能切换。旧 `/admin/posts/new`、`/admin/notes/new` 链接兼容跳转并预选类型；已有内容继续在各自编辑页保存。 - 笔记以独立数字 ID 保存，默认私密。支持 Markdown 编辑／预览／分栏、代码高亮、搜索、标签、分页、置顶及公开切换；所有设置需保存后生效。 - 笔记管理提供「导入笔记」入口，支持文件与语雀导入，默认私密；导入记录可直接跳转编辑。笔记暂未接入分发和 RSS。 - **公开全部私密笔记**：点击后读取所有分页、所有筛选条件之外的私密笔记数量，确认后按当次 ID 快照每批最多 100 条公开，并显示进度。本次快照之后新建或导入的笔记不受影响；失败停止，重新操作会重新读取私密列表。仅更新公开状态和修改时间，保留正文、标签、置顶与导入信息。 - **笔记树形管理**：后台目录沿用前台的多级结构，保留 `01 AIOPS`、`02 CI-CD` 等顶层名称与编号。点箭头展开或收起，点目录名查看自身及下级笔记，点具体笔记在右侧预览、公开／私密、置顶或删除，目录树持续保留。支持目录与标题搜索、全部展开／收起、目录内分页与批量管理；编辑后返回会恢复原目录和笔记。路径来自首个标签的多级目录，无需重新导入；旧 `group` 链接仍可使用。 - **笔记批量管理**：勾选当前页或全部筛选结果，可批量公开、设为私密、置顶、取消置顶和删除。翻页保留勾选，切换目录、打开笔记或修改搜索、标签、可见性筛选会清空勾选；全选只读取当前目录及其子目录内匹配笔记的编号与状态。确认后按固定选择每批最多 100 篇处理，显示进度，失败停止并刷新，删除末页后自动返回有效页码。公开／置顶操作保留正文和导入信息；删除不影响文章、专栏和媒体附件。 - 删除与未保存离开需要确认；会话过期保留当前页面输入，可在新页面登录后重试。