DevSpace:使用 React、Go 与 PostgreSQL 构建自己的数字空间

从技术博客、在线工具、资源导航到项目展示,详细介绍 DevSpace 的 React + Go + PostgreSQL 架构,以及静态生成、内容管理、阅读统计、媒体安全、SEO、数据库迁移与 Docker Compose 部署设计。

DevSpace:使用 React、Go 与 PostgreSQL 构建自己的数字空间封面

我希望有一个属于自己的空间,可以记录技术实践、整理常用工具、收藏优质资源,也能完整展示自己做过的项目。

DevSpace 就是围绕这些需求构建的个人网站。它将技术博客、在线工具、资源导航、项目展示和管理后台整合在一起,并提供内容发布、媒体管理、静态页面生成、阅读统计和容器化部署能力。

站点入口:访问 DevSpace。

这篇文章会从功能、技术选型、系统架构和工程实现几个方面,介绍这个项目是如何组织起来的,以及一些看起来很小、实际开发时却需要认真处理的问题。技术细节以撰写时的项目源码和接口定义为依据。

项目的功能围绕“记录、使用、整理和展示”展开。 博客承载长期内容,工具解决日常开发中的小问题,导航保存值得反复访问的资源,项目页面则记录作品的背景、技术和实现。

模块主要用途已有能力
首页汇总站点内容精选文章、最新文章、推荐文章、近期热门、工具和资源展示
技术博客记录实践与知识Markdown、分类标签、归档、搜索、阅读目录、关联阅读
在线工具处理常见开发任务JSON、Base64、时间戳、URL 编解码、UUID
资源导航整理外部资源分类、标签、站点信息、上下架管理
项目展示展示作品与实践项目介绍、技术栈、外部链接、发布管理
管理后台维护网站内容内容编辑、媒体管理、分类标签、站点设置、数据概览

这些模块共享站点布局、主题、基础组件和接口访问方式,同时保留各自的业务规则。例如,文章有发布时间和阅读统计,工具有固定组件注册表,导航资源则有独立的分类、标签与上架状态。

这种组织方式让网站能够逐步扩展,也让不同内容保持清晰的管理边界。

技术栈采用 React、TypeScript、Go、PostgreSQL 和 Nginx。 前端负责展示与交互,Go 提供业务 API,PostgreSQL 保存结构化数据,Nginx 提供静态页面并代理接口请求。

当前项目的主要技术组成如下,版本按仓库声明的主要版本或版本系列列出:

层次技术在项目中的作用
前端界面React 19页面和组件开发
类型系统TypeScript 5.9前端类型约束与接口使用检查
构建工具Vite 7开发服务、浏览器资源构建、静态生成器构建
页面路由React Router 7公开页面、管理后台和生成阶段的路由复用
数据请求TanStack Query 5、Fetch请求管理、缓存、加载状态与数据刷新
样式Tailwind CSS 4布局、主题和样式组织
基础组件源码形式的 shadcn 风格组件、Radix Slot按钮、输入框及组件组合
表单React Hook Form、Zod表单状态和数据校验
Markdownreact-markdown、remark-gfm、rehype-sanitize正文解析、扩展语法与安全处理
代码高亮rehype-highlight对支持的代码语言进行高亮
图标Lucide React界面图标
后端Go 1.26、chiHTTP 服务、路由和业务逻辑
数据访问pgx、sqlcPostgreSQL 连接与类型化查询
数据迁移goose数据库结构演进
数据库PostgreSQL 17内容、认证、媒体记录与阅读统计
对象存储本地存储、S3 兼容存储媒体文件保存
Web 服务Nginx静态页面、路由规则、缓存与 API 代理
部署Docker Compose源码构建、迁移、页面生成及服务编排
测试与检查Vitest、Testing Library、Playwright、Go 工具链单元测试、组件测试、浏览器测试与后端检查
接口契约OpenAPI、openapi-typescriptAPI 定义与前端类型生成

这些技术在项目中承担不同职责。例如,TanStack Query 管理服务端数据,而表单输入和工具计算结果仍由相应组件维护;数据库连接和对象存储操作集中在后端,前端通过 HTTP 接口访问业务能力。

整体架构将页面交付和动态业务分开处理。 公开页面提前生成 HTML,浏览器加载后再接管交互,并通过 Go API 获取实时数据。

访问过程可以理解为:

text
访客浏览器
    │
    ▼
HTTPS 入口
    │
    ▼
Nginx
    ├── 返回生成好的 HTML、CSS 和 JavaScript
    │
    └── 代理 API 与媒体请求
                │
                ▼
              Go API
                ├── PostgreSQL
                └── 本地媒体存储 / S3 兼容存储

页面生成发生在部署阶段:

text
数据库迁移成功
    │
    ▼
只读 Go API 就绪
    │
    ▼
Node 静态生成器读取公开数据
    │
    ▼
复用 React 页面生成 HTML、robots 和 Sitemap
    │
    ▼
完整站点生成成功后启动正式 API 和 Web

Node 在这里承担构建和生成工作,生产访问链路中没有常驻的 Node SSR 服务。最终 Web 镜像使用 Nginx,Node 运行环境、前端依赖和生成器构建目录不会进入 Web 镜像。

这让前端可以继续使用 React 开发页面,同时让文章正文以完整 HTML 的形式交付。

静态生成解决了内容页面的首次交付问题。 对博客而言,标题、摘要、正文、链接和页面元信息都应当随页面一起返回。

DevSpace 的公开页面会预先生成正文 HTML。访客即使关闭 JavaScript,仍然可以阅读已经生成的文章内容。浏览器启用 JavaScript 后,React 接管页面,继续提供主题切换、目录定位、搜索和在线工具等交互。

生成器复用公开页面的 React 路由和组件,并为每个页面创建独立的 QueryClient。页面所需数据通过匿名公开 API 获取,再用于渲染页面和构造前端启动数据。

逐页创建数据上下文,可以避免不同页面之间混入错误的缓存内容。写入 HTML 的数据还需要安全转义,防止文章内容或其他字段破坏页面结构。

这里也有一个明确的时效性边界:后台保存内容后,API 数据与静态 HTML 的更新时机不同。 已生成的正文、Sitemap 和其他静态页面,需要重新运行生成流程才能更新。浏览器接管后会刷新实时 API 数据,但这不能代替静态产物的重新生成。

同样,API 故障时,已经交付的静态正文仍提供基础阅读能力;搜索、后台和通过 API 提供的站内媒体,则仍然依赖后端服务。

前端按页面组织、业务功能和公共能力拆分。 路由与 Provider 负责应用入口,管理模块承载后台操作,业务功能模块处理阅读交互和工具逻辑,公共库则集中维护接口访问、契约类型、SEO 和页面数据引导。

静态生成部分单独组织,但复用实际公开页面,因此页面样式和正文展示逻辑可以共同维护。

前端还使用按路由延迟加载。管理后台、博客详情、工具页面等模块按需加载,减少首屏一次性加载全部功能代码的需求。

界面提供浅色、深色和跟随系统三种主题模式。主题偏好可以保存在浏览器本地,系统主题变化时也会相应更新。文章目录针对桌面和移动端提供不同的展示方式,图片则根据展示区域选择合适尺寸。

Go 后端采用分层结构组织业务。 请求从路由和中间件进入 Handler,再交给 Service 处理规则,由 Repository 与 Storage 完成持久化操作。

层次主要职责
Config读取并校验运行配置
HTTP / Middleware路由、安全响应头、超时、认证及请求约束
Handler解析参数、调用业务逻辑、组织响应
Service内容公开规则、媒体校验、阅读统计等业务行为
RepositorySQL 查询、事务和数据聚合
Storage本地文件与 S3 兼容对象存储操作

以媒体上传为例,Handler 接收请求,Service 校验文件类型、大小和图片内容,Repository 保存媒体状态,Storage 写入实际文件。每一层都有明确的工作范围。

数据访问使用 pgx,认证等查询通过 sqlc 生成类型化代码,部分内容聚合 SQL 保留在 Repository 层。SQL 参数使用占位符,查询条件和事务边界也集中在数据访问层处理。

这种结构方便针对不同问题分别验证:输入错误可以在参数和业务校验阶段处理,事务回滚可以在数据库层验证,存储失败则可以通过媒体生命周期恢复。

博客功能覆盖了写作、组织和阅读的完整过程。 文章支持草稿、预览、发布、下架和硬删除,并使用 Slug 构造访问地址。

文章的公开条件由后端统一判断:内容必须处于已发布状态,而且发布时间已经到达。草稿和未来发布时间的文章不会出现在公开查询中。

发布时间输入按浏览器本地时区理解,再转换为带时区的 ISO 时间提交。这可以明确区分作者输入的本地时间与服务端保存、比较的时间,减少部署环境时区差异带来的歧义。

后台 Markdown 编辑器支持编辑、预览和分栏实时预览,并提供标题、加粗、斜体、链接、代码块和列表等快捷插入操作。表单保留未保存提醒、保存中防重复和错误反馈,降低长文编辑过程中的误操作风险。

阅读页面则提供:

  • 标题、摘要、作者信息和发布时间;
  • 分类、标签与文章封面;
  • 基于正文标题生成的目录;
  • 当前阅读位置提示和页面阅读进度;
  • 代码块语言标识与复制;
  • 文章链接复制;
  • 上一篇、下一篇和相关文章。

其中,上一篇和下一篇按公开文章的发布时间与 ID 确定顺序,保证相同发布时间下仍有稳定结果。

相关文章最多返回 4 篇,只考虑共享分类或标签的公开文章,再按共享标签数、共享分类数、时间和 ID 排序。如果没有关联内容,就不补充无关文章。

首页承担了内容编辑和发现入口的作用。 它将最新、精选、推荐和热门分开处理,每个区域都有清楚的数据来源。

首页内容返回上限含义
最新文章6 篇最近发布的公开文章
精选文章4 篇编辑明确标记的精选内容
推荐文章6 篇编辑明确标记的推荐内容
近期热门6 篇近 30 天有有效阅读的公开文章
精选工具5 项适合首页展示的工具
精选导航6 项适合首页展示的资源
精选项目3 项适合首页展示的项目

首页聚合数据在同一 SQL 快照下返回,包含这些内容及公开内容计数,减少同一次首页请求中不同区域数据状态不一致的问题。

置顶、精选和推荐是独立属性。置顶只影响博客列表,精选和推荐分别服务于对应展示区域。精选为空时,页面不会拿最新文章填充精选数据。

热门文章则要求近 30 天计数大于零,并按近期阅读量、发布时间和 ID 降序排列。它反映的是近期内容活跃程度。

阅读统计有明确的触发条件和隐私边界。 普通 GET 请求不会直接增加阅读量,静态页面生成也不会产生阅读次数。

浏览器只有在页面累计可见满 10 秒后,才会调用:

http
POST /api/v1/posts/{slug}/views

页面隐藏时暂停计时,离开页面时取消当前计时。这样可以减少快速误点、后台标签页停留和页面预加载对统计的影响。

浏览器使用按 UTC 日轮换的随机 UUID v4 作为当日匿名标识。标识保存在 localStorage;本地存储不可用、启用 DNT/GPC,或者处于演示模式时,客户端跳过采集。

服务端在阅读统计中只保存标识的 SHA256,不保存原始标识、IP 或 User-Agent。同一匿名标识、同一文章、同一 UTC 日最多计数一次。

去重与计数更新使用文章行锁、唯一约束和事务,确保并发上报时累计值、每日值和去重记录保持一致。统计更新也不会改变正文的更新时间。

数据保留按用途区分:

数据保留方式
累计阅读数随文章保留
每日聚合保留近 30 天
匿名去重记录保留当前 UTC 日

文章修改 Slug 后保留统计,硬删除文章时级联清理相关记录。正常 API 启动及每小时执行清理,只读生成 API 不运行这项写操作。

服务端还对每个标识实施每分钟最多 60 次的限制,进程内最多保留 10000 个限流标识。已知机器人以及 DNT/GPC 请求不写入统计;客户端上报失败也不会阻断阅读或建立持续重试队列。

因此,这个指标适合观察内容阅读情况,但不代表独立自然人数,也不构成完整的反作弊系统。当前后台展示累计有效阅读,尚未提供按日趋势图。

在线工具将计算放在浏览器完成。 当前内置五个工具:

工具能力
JSON 格式化格式化、语法校验和压缩
Base64UTF-8 文本编码与解码
时间戳转换秒或毫秒转日期、带时区日期转时间戳
URL 编解码URI 组件编码与解码
UUID批量生成 1—100 个 UUID

工具输入在当前浏览器处理,不发送到后端。界面提供示例输入、清空、复制结果以及适用场景下的输入输出交换。

实现中也处理了常见边界。例如,Base64 解码会检查字符和填充,并验证结果能否解码为 UTF-8;时间戳转换要求明确选择秒或毫秒,日期转时间戳要求输入带时区;UUID 使用浏览器安全随机数能力。

工具输入上限为 1 MiB,避免无界输入给浏览器造成额外负担。

后台维护的是这些工具的名称、说明、分类、排序和启用状态等元数据。工具组件通过固定注册表提供,不支持在后台录入任意 JavaScript。新增工具需要同时更新前端注册、种子数据和后端校验,使可执行代码仍然进入正常开发与检查流程。

资源导航和项目展示让内容有了更多组织方式。 导航支持分类、标签和上下架管理,适合整理开发文档、设计资源、学习资料与常用站点。

项目展示支持介绍正文、摘要、封面、技术栈和外部链接,同时具备草稿、预览、发布、下架和删除能力。项目可以用来记录一个作品解决的问题、使用的技术,以及实现中的关键选择。

外部链接只接受安全的 HTTP(S) 地址,并在展示时使用相应的链接保护属性。

标签、分类和技术栈关联也有持久化规则:被内容引用的分类或标签不能直接删除,检查范围包含非公开内容;导航标签、项目技术栈和工具批量更新在事务内完成,失败时整体回滚。

这可以避免一次保存只成功了一部分,或者删除分类后留下难以解释的内容关系。

媒体系统将文件和数据库状态一起管理。 图片上传看起来只是一个按钮,实际需要同时处理格式安全、文件落盘、数据库记录、内容引用和删除失败等问题。

DevSpace 接受 JPEG、PNG、WebP 和 GIF,单文件最大 10 MiB。服务端会检查扩展名、声明 MIME、文件签名、实际解码结果以及图片尺寸和像素上限,并拒绝 SVG 和伪装输入。

文件使用随机对象键保存。原始文件名只作为展示信息,不参与实际存储路径。

媒体通过统一 Store 接口支持本地存储和 S3 兼容存储,业务层可以使用一致的操作方式。媒体记录则采用三个生命周期状态:

text
pending  →  ready  →  deleting
待完成      可读取     删除处理中

只有 ready 状态允许公开读取。上传或删除失败时保留可恢复记录,未完成对象可以通过后台清理。

另一个关键规则是引用保护。文章、项目、导航和站点配置中使用的图片不能直接删除,草稿和下架内容中的引用也会参与检查。保存内容与删除媒体使用共同的事务锁和引用校验,处理并发操作下的竞争问题。

媒体通过同源 API 公开提供,因此其访问模型适用于网站公开图片,并不承担私密附件的权限控制。

图片优化采用固定尺寸和按需转换。 对站内可读取图片,媒体接口支持三种宽度:

text
?width=320
?width=640
?width=1280

处理只会缩小原图,不会放大,也不接受外部 URL 作为图片代理来源。无透明度的结果生成 JPEG,有透明度的结果生成 PNG。

对于 GIF、检测到 EXIF 的图片、APNG、尺寸不足或转换没有收益的情况,会回退原图,避免破坏动画、方向信息或增加不必要的处理。

转换结果使用进程内 LRU 缓存,最多 256 项、64 MiB,复用时间为 10 分钟,同时最多处理两张图片。这些限制约束的是缓存和处理并发,不能等同于整个进程的内存上限。

即使命中缓存,或者收到 HEAD、条件请求,服务端仍会先检查数据库中的媒体状态,防止图片删除后继续从缓存返回。

媒体响应支持 ETag 和 Range,并使用需要重新验证的缓存策略。前端主要阅读场景通过 srcset 与 sizes 选择适合的图片尺寸,加载失败时回退原地址。

派生图片只保存在内存缓存中,不生成额外的持久文件,因此也不增加单独的派生图片备份卷。

Markdown 渲染同时考虑了内容安全和浏览器开销。 正文支持常用 Markdown 与 GFM 语法,渲染过程中禁用原始 HTML,检查链接协议,并执行 sanitize。

代码高亮仅处理显式支持的语言,不进行任意语言自动检测。单个代码块的高亮预算为 16K UTF-16 单元,每次渲染累计最多 64K UTF-16 单元;超出范围或不支持的语言以纯文本展示,复制功能保留原文。

这个限制让很长的日志、大段生成代码或者未知语法仍然可以被阅读,同时避免高亮处理占用过多资源。

SEO 信息随每个公开页面一起生成。 页面包含各自的标题、描述、canonical、Open Graph、Twitter 卡片信息,以及适用的 JSON-LD 结构化数据。

生成页面清单来自:

http
GET /api/v1/seo/urls

该接口每页返回 1000 条,生成流程最多处理 50000 个页面,覆盖公开文章、项目、启用工具、分类、标签、归档及有效分页。

草稿、未来内容和未知路径不会进入生成清单。canonical 和 Sitemap 统一使用配置的 PUBLIC_ORIGIN,生产环境要求 HTTPS。

后台、搜索和筛选页面采用 noindex 的 SPA 方式,公开内容页面则生成实际 HTML。Nginx 对未知路径和超范围分页返回 404,对非法分页参数返回 400,对尾斜杠执行 308 重定向。

缓存策略也按资源类型区分:HTML 和 XML 使用 no-store,带哈希的静态资源使用长期 immutable 缓存,API 与媒体保留上游的 Cache-Control 和 ETag。

这些细节让页面地址、状态码、搜索引擎信息和浏览器缓存保持一致。

静态产物需要完整生成后才能替换。 生成过程中如果某一页失败,整个流程不能把不完整站点切换为正式结果。

因此,生成器在全部页面成功后才替换最终站点目录,失败时保留完整旧产物。生成前后会比较清单,并使用目录锁阻止并发生成;Windows 文件占用导致的切换失败则进行有限重试。

发布还额外保留上一发布的主要哈希资源,照顾仍然打开旧页面的浏览器。

需要明确的是,生成过程包含多个 API 请求,它们并不处于同一个数据库事务中。只读生成 API 可以阻止通过自身写入,但生成期间仍需要避免其他连接直接修改数据库。定时内容如果恰好跨过生成时间边界,也可能需要重新生成。

这些约束决定了发布流程必须有顺序,并且同一环境不能同时运行多套 Compose 发布操作。

后台认证使用服务端会话。 管理员通过命令显式创建,系统没有默认密码,也不提供访客注册。

密码使用 bcrypt 哈希。登录成功后生成随机会话令牌,数据库只保存令牌的 SHA256 哈希,并在查询时检查过期和撤销状态。

会话 Cookie 使用 HttpOnly、SameSite=Strict,生产环境强制 Secure 和 HTTPS。携带 Cookie 的写请求必须提供完整匹配的 Origin,以约束跨站请求。

登录接口还实施每个直接来源 IP 每分钟 5 次的进程内限流。目前不信任 X-Forwarded-For,因此代理后的用户可能共享限流额度。扩展到多实例时,还需要设计可信代理和共享限流策略。

公开接口与管理接口分别组织查询路径,避免把包含草稿等管理数据的结果直接用于公开页面。公开站点设置也只返回展示资料,不返回存储密钥。

数据库结构通过迁移和兼容策略共同演进。 主要数据围绕管理员与会话、文章与分类标签、工具、导航、项目、媒体、站点设置和阅读统计展开。

多对多关系使用关联表表达,数据库约束参与维护唯一性和引用关系。文章统计按文章 ID 关联,因此文章地址修改不会重置历史计数。

goose 负责执行迁移,已经应用的迁移不再改写。数据库兼容策略记录应用最低要求、目标迁移版本及回退兼容范围,结构变化需要考虑旧代码能否继续读取和写入。

服务提供两个不同的检查入口:

接口检查内容
/healthz进程是否存活
/readyz数据库最低迁移版本和必需表是否满足要求

就绪检查不会自动迁移数据库。迁移作为部署中的独立步骤执行,成功后才继续后续服务启动。

这样可以区分“进程已经启动”和“应用具备正常处理业务的条件”。

部署由根目录 Docker Compose 配置统一组织。 服务器从源码构建镜像,不需要单独安装项目所需的 Node.js 或 Go 工具链。

主要服务职责如下:

服务职责
postgres数据库
migrate一次性数据库迁移
generator-api为页面生成提供只读公开 API
generate一次性静态站点生成
api正式业务 API
webNginx 静态站点与接口代理
admin运维时显式创建管理员

部署顺序由依赖条件控制:

text
PostgreSQL 就绪
    → 迁移成功
    → 只读生成 API 就绪
    → 静态页面生成成功
    → 正式 API 就绪
    → Web 启动

只读生成 API 同时采用 HTTP 写入拦截、数据库默认只读和媒体只读挂载,并停用阅读统计清理任务。

正式更新按照 README 中的流程先停止旧服务,再构建和启动。这个流程存在停机窗口,当前没有蓝绿部署或零停机切换机制。

数据库、媒体和静态站点分别保存在 Docker 命名卷中,容器重建不会自动删除这些数据。卷名称需要保持稳定,更新也不能使用会删除数据卷的操作。

备份与恢复需要独立维护,包括数据库、媒体、服务器配置和 S3 对象。切换旧源码之前还需要确认数据库兼容性;项目不提供自动数据库回退。

接口契约与检查流程帮助各层保持一致。 API 定义使用 OpenAPI,并通过生成流程产生接口文档和 TypeScript 类型。SQL 查询生成代码也从查询源文件生成,避免手工修改生成结果造成偏差。

前端配置了 ESLint、Prettier、Vitest、Testing Library 和 Playwright。后端使用 Go 测试与静态检查,并通过集成测试验证数据库和 HTTP 行为。

检查范围覆盖工具逻辑、Markdown、主题、图片回退、管理内容、媒体生命周期、阅读统计及静态生成等实际行为。部署配置另有解析测试和构建检查。

集成测试显式使用隔离的 TEST_DATABASE_URL,原生开发和隔离测试通过进程环境提供配置,不读取服务器部署配置。

性能优化也保留了可复现路径:首页和列表查询先在同一 SQL 快照中选出需要展示的 ID,再补齐相关字段;性能画像与新旧 SQL 等价检查用于确认优化前后的行为。

这些检查说明项目具备相应验证手段,但不能直接推导出线上吞吐量或响应时间,也不能替代目标 Linux、HTTPS 和对象存储环境的实际验收。

当前版本仍有清楚的扩展边界。 网站已经具备个人内容平台的主要能力,但尚未实现评论与访客账号、跨模块全站搜索、后台一键静态发布、自动定时生成、蓝绿部署、共享限流和完整审计与会话维护。

这些能力如果继续加入,都需要与现有规则衔接。例如,自动发布要协调数据库可见性和静态生成时间,评论系统需要新的身份与内容治理机制,多实例部署需要共享限流,私密附件则需要与现有公开媒体不同的访问控制。

后续扩展会继续围绕内容维护和阅读体验展开,同时保留公开数据边界、媒体引用保护、接口契约生成和数据库兼容策略,让新增功能能够融入现有系统。

交流与讨论

留下你的思考,友善交流。昵称和评论将公开展示,请勿填写个人敏感信息。

纯文本 · 最多 2000 字 · 请勿重复发送

正在加载…