从零到上线：我如何搭建 KunSpace 并实现国内外双轨部署

写在前面

KunSpace 是我的个人网站——作品集、博客、留言板、访客统计，一个链接就能让别人了解我。

这篇文章记录的是：从写需求文档，到代码落地，再到国内外都能访问，我实际走过的一整条路。如果你也想做自己的个人站，或者已经在用 Vercel 但国内朋友打不开，希望对你有用。

一、从需求文档开始

我没有一上来就写代码，而是先想清楚「这个网站要干什么」。

在项目里整理了这些文档：

文档	作用
开发文档	产品规划、页面结构、技术选型
设计规范	颜色、字体、布局标准
内容清单	头像、作品、博客要写什么
使用指南	怎么改内容、怎么部署

核心页面很明确：

首页 — 自我介绍 + 精选作品 + 最新博客
关于我 — 经历、技能、为什么叫「全栈工程师」
作品集 — 项目详情，链到 GitHub
博客 — Markdown 写文章
留言板 — 访客留言，仅站长可见
联系 — 邮箱、GitHub

先把「做什么」定下来，后面改代码就不会乱。

二、技术架构选型

最终技术栈：

Next.js 15 + TypeScript + Tailwind CSS + Framer Motion
内容：Markdown（博客 / 作品）
数据：Upstash Redis（留言 + 访客统计，线上）/ 本地 JSON（开发）
部署：Vercel（海外）+ 腾讯云轻量（国内）

为什么选 Next.js？

个人站需要 SEO、静态页面性能、API 路由（留言、统计）
和 Vercel 是「亲儿子」关系，海外部署省心
App Router + Markdown，改内容不用动复杂后端

项目结构大致是：

src/
  app/          # 页面与 API 路由
  components/   # UI 与区块组件
  content/      # 博客、作品 Markdown
  lib/          # 站点配置、留言、统计、鉴权
public/         # 头像、图片等静态资源
docs/           # 项目文档
deploy/         # Nginx、PM2 配置示例

站点文案、导航、关于页内容集中在 site-config.ts，改一处全站生效。

三、功能开发：几个关键模块

1. 关于我

经历按方向分类：语音唤醒、音视频产品、测试自动化，并单独解释「全栈」在智能硬件语境下指什么——不是简单的前后端 Web，而是系统、算法、应用、音效、工程全链路。

2. 留言板 + 访客统计

留言：访客提交，站长在 /admin/guestbook 查看
统计：自动记录 PV/UV、热门页面、最近访问，在 /admin/analytics 查看
都用同一套管理员密码，数据存 Upstash Redis（线上）或本地 JSON（开发）

3. 版本号与缓存

版本号跟随 package.json，页脚显示 v1.0.x
开发环境加了静态资源防缓存，改头像、改样式后刷新即可看到，不用老清浏览器缓存

4. 视觉

可配置背景光斑、渐变
卡通风 SVG 头像（音频 + 科技感，而不是一个字母 K）

四、海外部署：Vercel + GitHub 私有仓库

代码放在 GitHub 私有仓库（KunLiam/KunSpace），不需要公开源码。

流程：

推送代码到 GitHub
Vercel 用 GitHub 登录，Import 私有仓库
配置环境变量：ADMIN_PASSWORD、UPSTASH_REDIS_REST_URL、UPSTASH_REDIS_REST_TOKEN
Deploy，得到 https://kun-space.vercel.app

之后每次 git push，Vercel 约 1～2 分钟自动更新。

踩坑： 我在国内直接访问 .vercel.app 经常超时，用 VPN 才能打开——说明部署成功，是网络环境问题，不是代码坏了。

五、国内部署：为什么要第二条链路？

国内很多人不会用 VPN。要让朋友、同事、家人直接打开，需要服务器在国内。

我选了 腾讯云轻量应用服务器（2核2G，广州，Ubuntu + Docker 镜像，新用户可试用 1 个月）。

部署步骤摘要

防火墙：放行 22、80、3000
代码：git clone 或本机 scp 上传（GitHub 在国内服务器上 clone 很慢，scp 往往更快）
环境变量：.env.production.local 写入密码和 Upstash

Docker：

sudo docker build -t kunspace .
sudo docker run -d --name kunspace --restart unless-stopped \
  -p 3000:3000 --env-file .env.production.local kunspace

Nginx：反代 80 → 3000，访问 http://公网IP 不用加端口

踩坑记录：

问题	原因	解决
Docker permission denied	ubuntu 用户默认无 Docker 权限	命令前加 `sudo`
浏览器超时	没加 `:3000` 或防火墙未开 3000	先开 3000 测通，再配 Nginx 用 80
git clone 极慢	国内访问 GitHub	改用 scp 从本地上传
Upstash Token	误选 Read-Only	取消只读，用可写 Token

国内访问地址：http://129.204.149.100（示例，以你服务器 IP 为准）。

更完整的命令见仓库内 docs/国内部署指南.md。

六、双轨部署：最终形态

                    ┌─────────────────┐
  海外访客 ────────►│ Vercel          │  kun-space.vercel.app
                    │ git push 自动部署 │
                    └─────────────────┘

                    ┌─────────────────┐
  国内访客 ────────►│ 腾讯云轻量       │  http://公网IP
                    │ Docker + Nginx  │  git pull / scp 后手动更新
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ Upstash Redis   │  留言 + 访客统计（共用）
                    └─────────────────┘

同一套代码，两个入口，互不影响。

七、以后怎么更新？

目标	操作
海外 Vercel	本地改代码 → `git push` → 自动部署
国内腾讯云	`git push` 后，SSH 进服务器执行 `bash scripts/update-server.sh`（或 scp 上传 + 重建 Docker）

只改了环境变量：sudo docker restart kunspace 即可，不必 rebuild。

八、还没做、但可以规划的

域名 + ICP 备案：试用期满续费 ≥1 年，买域名备案后，国内用 https://www.xxx.cn 更正式
HTTPS：备案后在服务器用 certbot 免费证书
CI/CD：GitHub Actions 推送到服务器自动部署（进阶）

结语

这一趟下来，我最大的感受是：

先写文档再写代码，少走弯路
Vercel 适合海外，国内要另备一条链路
私有仓库 + 双轨部署，既保护源码，又照顾国内访客
踩坑很正常——防火墙、Docker 权限、GitHub 速度，逐一解决就好

KunSpace 还在持续迭代。如果你也在做个人站，欢迎留言交流，或去看看关于我和作品集。

当前版本：v1.0.2 · 构建工具：Next.js + AI 辅助开发