用 AI 智能体做一个真正上线的个人独立站

——以「Bienberlain 拾知录」的开发过程为例

版本：2026 年 10 月 19 日

适合读者：没有编程经验，愿意按照步骤操作，希望拥有个人主页、博客、教程站或作品站的人。

目标：做出一个自己能维护、别人能通过公网访问、关闭自己的电脑后仍能运行的网站。

你负责确定内容、风格、预算和验收结果；AI 负责读取项目、写代码、运行、测试、修复和准备部署。需要注册账号、身份验证、购买资源或输入密钥时，你在对应的官方页面操作。

本文有两类内容：

• 项目复盘：来自 Bienberlain 拾知录现有代码、Git 记录、项目文档和相关开发聊天。
• 新手工作流：根据这些经历整理出的推荐顺序。服务器部署部分是可执行的准备流程，不能当成本站已经部署成功的记录。

截至本文整理时，本站本地地址为 http://localhost:3000/。可核查记录显示，项目已经完成多轮本地开发与上线前验收，尚没有本次可核验的正式域名、HTTPS 和公网部署结果。文中不会将「准备上线」写成「已经上线」。

先看这一页：整个过程怎么走

确定网站用途、第一版范围
    ↓
装好一个能操作项目文件的 AI 智能体
    ↓
建立项目文件夹、需求文档和 Git 存档
    ↓
给参考图，确认首页与文章页的静态布局
    ↓
先跑通「新增内容 → 发布 → 访客阅读」
    ↓
补后台、真实文章、手机适配和必要动效
    ↓
换一个聊天或工具，独立验收
    ↓
修复问题，验证生产构建与数据备份
    ↓
确认服务器地域、预算、域名及适用备案要求
    ↓
服务器部署 → 域名解析 → HTTPS → 自动运行
    ↓
用手机流量、无痕窗口、重启测试完成公网验收
    ↓
持续发布内容；每次改版先备份，再更新，再验收

第一次做，只记住三个阶段性目标：

1. 第一阶段：本地可用。 自己的电脑上可以打开，按钮有真实作用，内容保存后不会丢。
2. 第二阶段：可以部署。 生产构建能启动，部署资料齐全，数据库和上传文件有明确存放位置。
3. 第三阶段：公网可用。 另一台设备不登录你的开发账号，也能通过正式 HTTPS 地址访问；你的电脑关机后网站仍然可用。

三者分别验收。AI 说「已经完成开发」，只说明你可以开始检查，不能直接替代后两个阶段。

按你现在的进度阅读

• 从没做过网站：从「准备环境与资料」开始，逐步执行后面的 10 步。
• 想先让智能体开工：直接复制「十五、第一次动手，可以直接从这段开始」。
• 已有本地网站：从「第 5 步：换一个聊天或工具验收」开始，再准备部署。
• 已有拾知录项目：先核对下方复盘与当前工作区，不要重新初始化已有数据库。
• 只是遇到报错：查「十四、卡住时，对照这张表」。

如果你已经有基础，走这条快速路线

确定需求与验收条件 → 选一个开发智能体 → 完成页面与数据闭环 → 独立检查 Git diff、权限和生产模式 → 保存代码版本与完整数据备份 → 在有持久磁盘的 Linux 服务器部署 → 配 DNS 与 HTTPS → 手机外网验收 → 设置备份、证书续期与更新流程。

本文的主路线是「可登录后台的个人内容站」。如果只是展示个人介绍和几篇文章，可以先做静态站，跳过数据库、管理员、上传和服务进程这些步骤；不要把两条路线的部署命令混着用。

一、回看拾知录：哪些做法值得保留，哪些顺序可以调整

1. 实际开发历程

下表按可核查记录整理。时间表示对应阶段有记录，并不表示每阶段只发生过一次修改。

当前项目的 Git 提交记录集中到 10 月 7 日，后续还有大量工作区改动。因此，只看 Git 提交记录无法还原后续全部开发过程，需要结合当前文件与开发聊天。

对拾知录而言，发布前还要核对：后续新增的组件、迁移、脚本和必要素材，是否已经包含在准备部署的完整版本中。只推送早期提交，服务器不会自动得到本地后来增加的功能。

2. 这次经历最有用的六个提醒

先定网站要做什么。 原版同时包含内容、服务推广、案例与新闻，后来才收敛为个人内容分享。对新手，第一版先明确主要用途，技术和文案才容易保持一致。

审美要求用参考图表达。 「高级一点」「科技一点」不够具体。拾知录后来用页面参考、静态设计稿和逐页反馈推进，才形成更明确的视觉方向。

一张效果图和一个能用的网页，需要分别验收。 图里可以把文字、玻璃、背景和动画放在理想位置；真实网页还要处理窄屏、长标题、点击、滚动、加载与阅读。

把任务写成动作。 项目中出现过把改造提示词当成背景规则、继续审计却没有开始实施的情况。交给 AI 时应明确：现在执行哪个任务、读取哪个文件、做出什么结果。

验证真实操作结果。 曾经出现「代码块看起来存在，复制组件没有真正生效」「已登录管理员看得到，访客读不到文档图片」等问题。不能只检查源码里有没有按钮或组件。

代码、内容数据和上传文件分别保管。 回退代码不能自动恢复文章与附件；单独备份数据库也可能缺文件。测试应使用独立数据，备份应验证能否恢复。

3. 怎么理解历史验收数字

首版有 80 项验收记录，10 月 2 日阶段有 103 项记录，10 月 18 日的开发聊天记载：开发环境与 standalone 生产运行各完成 181 项功能及安全验收。

这些数字属于不同时间、不同代码和不同覆盖范围，不能直接当成今天重新测试的结果。旧 README 和测试记录还保留了早期状态；读文档时要核对日期、当前代码和最新交接记录。

10 月 18 日的记录也明确保留了真实服务器、HTTPS、真机浏览器和依赖审计剩余告警等边界。验收报告应该说明「测了什么、在哪测、哪些还没测」。

二、先选一个智能体，不用同时开三个

这里的「智能体」指能在你授权的目录里读取文件、修改文件、运行命令的工具。普通网页聊天可以帮你整理需求；要直接在电脑里开发，还需要对应的文件与执行能力。

1. 三种工具怎么接入这套流程

Codex 当前官方入门说明提供了本地文件夹、Codex 开发入口、CLI 与 IDE 等使用路径，具体界面以你安装的版本为准。OpenAI 官方入门说明

Claude Code 官方文档说明了在项目目录启动、读取代码、执行修改与验证的基本方式。Claude Code 官方快速入门

DeepSeek Harness 官方指南要求先配置模型，再选择工作区，之后才能在会话中执行任务。DeepSeek Harness 官方使用指南

2. 推荐的协作方式

一个人、一个开发智能体，也能做完整个网站。 需求、开发、验收可以分成不同聊天。

如果有多个工具，可以让一个负责开发，另一个独立验收。分工由当前任务决定，例如：

这些角色可以轮换。不要把「Claude 只能开发、Codex 只能审查」当成工具限制。

同一时间尽量只有一个智能体修改同一份工作目录。验收者需要修改时，先结束上一轮写入，并说明现在由谁接手。

3. Claude Code 接 DeepSeek 时，区分工具与模型

Claude Code 是操作项目的工具；接入 DeepSeek 后，提供模型服务的是 DeepSeek。DeepSeek 官方提供 Anthropic 兼容接口，地址为：

https://api.deepseek.com/anthropic

按 DeepSeek 官方接入 Claude Code 说明 配置当前支持的模型、认证变量与路由；不要直接照抄旧教程的模型名。接口基础说明见 Anthropic 兼容接口文档。

用一句「请查看当前目录，只回复项目路径和文件概况」验证。能正常回复目录内容、能创建一个测试文件，才说明开发环境已经连通；聊天能回答常识问题，不足以证明它能操作项目。

API Key 只填入工具配置或受保护的本地环境，不写进需求文档、文章、网页源码或截图。

4. DeepSeek Harness 的简短启动方式

官方仓库当前提供的 npm 启动命令是：

npx @deepseek-ai/dsh web

安装 Node.js 后，在项目目录打开终端运行。首次运行可能需要下载依赖。默认 Web UI 地址为 http://127.0.0.1:3080/；进入后在 Settings → Models 配置模型，再 Choose workspace 选择项目目录。

这是智能体工具的操作界面，不是你要交付的个人网站。网站开发服务器可以使用 3000 端口，两者分别运行。官方仍将 Harness 标记为开发预览，升级前看对应说明。DeepSeek Harness 官方仓库

三、准备环境与资料

1. 电脑上准备什么

下载入口：Node.js、Git、VS Code。

Node.js 选择仍受支持、且满足项目要求的 LTS 版本。拾知录当前要求至少 22.13.0，已有部署文档建议 24 LTS；新项目让 AI 同时核对框架要求与官方支持周期。Node.js 官方版本说明

Windows 可以从开始菜单打开 PowerShell；macOS 可以用聚焦搜索打开「终端」。装完软件后，重新打开一个终端，再依次执行：

node -v
npm -v
git --version

正常情况会分别显示版本号。出现「找不到命令」时，先修复安装或 PATH，暂时不要继续生成网站。

2. 建一个清楚的项目位置

在电脑上建文件夹，例如：

• Windows：C:\Projects\my-personal-site
• macOS：你的个人目录下的 Projects/my-personal-site

在智能体里选择这个文件夹。目录名尽量简单，不要把桌面、下载文件夹或整个个人目录当成网站项目。

建议资料结构如下，由 AI 帮你建立即可：

my-personal-site/
├── README.md                  怎么安装、启动和构建
├── AGENTS.md                  项目规则，供支持它的智能体读取
├── CLAUDE.md                  使用 Claude Code 时的简短入口，可引用共同规则
├── HANDOFF.md                 目前做到哪、如何验证、还有什么问题
├── .env.example               环境变量模板，不含真实秘密
├── docs/
│   ├── 需求说明.md
│   ├── 设计说明.md
│   ├── 验收记录.md
│   └── 部署说明.md
├── design/                    参考图、设计稿和素材来源
└── 其他网站代码……

单独、受保护的位置：
├── 数据备份                   数据库与上传文件的成套备份
└── 凭据与恢复资料             与代码仓库分开保存

这些文件是为了方便你交接。Codex 可以读取 AGENTS.md 作为仓库指导；其他工具的自动读取规则以其文档为准，必要时在任务开头明确要求读取共同规则。别假设换一个工具会自动知道前一个聊天的全部内容。OpenAI 官方开发工作流说明

3. 提前准备最少一批真实内容

先准备：站名、一句话介绍、关于自己的一段话、3 篇文章、一个联系方式、几张有使用权的图片。

如果你想做教程站，3 篇文章最好分别包含：

• 一篇普通短文，用于看基本排版。
• 一篇含标题、长代码、图片、表格的长教程。
• 一份真实 PDF 或 DOCX，用于验证你确实需要的导入能力。

允许先用明确标记的演示内容开发。上线前按标记核对处理，不能用一次「清空所有内容」替代清理演示数据。

4. 预算先记哪些项目

先按预算上限比较，再购买。本文不固定云产品活动价，也不承诺某个套餐能支撑任意流量。

四、第 1 步：让 AI 把想法变成一份能执行的任务书

你要做的事： 打开聊天工具，说明想给谁看、放什么内容、如何更新、是否需要后台。

不用先研究前端框架。你可以直接复制：

我想做一个个人独立站，请先整理需求，不要开始写代码。

网站名称：【填写你的站名】
主要用途：【个人博客 / AI 教程 / 摄影作品 / 个人主页】
目标读者：【填写谁会来看】
主要内容：【填写你想发布什么】
更新方式：【希望登录后台发布；或愿意把文章文件交给 AI 更新】
视觉方向：【写一两句话，并附 2～3 张参考图】
是否需要文档阅读：【不需要 / PDF / Word 导入 / 都需要】
是否保存私人资料：【不保存；或具体写清哪些只能自己看】
最终目标：部署到公网，关闭我的电脑后，别人仍能打开。
主要访问地区：【填写】
每年可接受的站点费用上限：【填写；不确定就写暂不购买】

请输出：
1. 网站定位和一句话介绍。
2. 第一版页面、核心功能和暂缓功能。
3. 访客与管理员各自的完整操作流程。
4. 公开内容、草稿、私人数据和文件的边界。
5. 适合新手维护的技术方案与部署方式，说明是否需要持久化磁盘。
6. 可以逐条实际验证的验收条件。
7. 本地开发、上线前检查、公网部署三个阶段的交付物。

小问题采用合理默认值并写明；只问会改变网站方向的关键问题。
请特别检查：本地能运行的方案能否部署到我选的服务器。

正常应该得到： 一份写清页面、功能、数据和验收条件的任务书。

把它保存为 docs/需求说明.md。如果 AI 直接设计出商城、会员、评论、复杂账号系统，让它收回到你的真实范围。

用拾知录的场景举例

拾知录当前公开分享教程、笔记和工具使用经验，读者可以免费阅读和下载。教程中的付费安装与教学推广段落已移除。开发阶段保留的私有客户管理模块属于后台测试功能，普通个人内容站不需要照搬。

验收条件怎么写

进入下一步的条件： 你能用自己的话说清网站第一版要做什么，并认可这些验收条件。

五、第 2 步：先看布局，再逐步实现视觉与动效

拾知录在视觉上花了多轮修改。对新手，先确定首页和文章页，比直接让 AI 重做全站更容易判断。

1. 给 AI 什么参考

选择 2～3 张参考，逐张写清：

参考图 A：喜欢它的导航、标题大小和留白。
参考图 B：喜欢它的深色背景和玻璃面板。
参考图 C：只参考文章目录和正文排版。

网站实际内容使用我的资料。
先做首页、文章页的静态布局，给我看桌面和手机效果。
先保证真实文字可读、功能位置明确，再添加动效。

参考网站的效果可能依赖 3D 模型、视频或特定组件。让 AI 说明需要哪些素材、授权与性能成本，再决定要做多像。

2. 可直接复制的设计任务

请根据 docs/需求说明.md 和我提供的参考图做视觉方案。

这一阶段先交付首页与文章页的静态设计稿或可运行静态原型。
请说明：字体、颜色、间距、导航、卡片、正文、目录和手机布局。
设计必须放入真实中文长标题、长段落、代码块与表格进行检查。

背景、文字、操作面板之间要有明确层次。
透明面板仍需保证文字对比度。
附上图片、字体、图标和组件的来源及使用条件。

如果已有可运行项目，请先保留可恢复版本。
不要为了换视觉就更换数据库、接口或整个技术栈。

正常应该看到： 可以打开的原型或明确标记的设计图，而不是只有一段「高端科技风」的描述。

3. 反馈说到具体位置

可以这样反馈：

教程详情页：
1. 目录宽度收窄，长标题仍能读全。
2. 正文行宽控制在适合阅读的范围。
3. 手机端目录改成可展开入口。
4. 长代码只在代码框内滚动，不撑宽整页。
5. 固定导航不能挡住目录跳转后的章节标题。

请只调整这些位置，并给我修改后的实际页面截图。

4. 动效放在哪一步

先完成静态布局与功能闭环，再一处一处添加。拾知录的玻璃、场景、粒子和文字动画属于个性化设计，第一次建站可以先保留一个主要效果。

每加一项，检查：加载时内容是否可见、手机是否卡顿、背景是否挡点击、系统减少动态效果时能否降级、WebGL 不可用时有没有静态替代。

进入下一步的条件： 首页与文章页的布局方向已经清楚，且能接受它们在手机上的样子。

六、第 3 步：建立项目，先完成一条真正能用的链路

1. 本文主路线采用什么结构

拾知录当前采用 Next.js + React + TypeScript，Prisma 管理 SQLite 数据，前台、后台与接口处于同一个项目。小型单管理员内容站可以参考这个结构。

新项目让 AI 选择当前受支持、能兼容所需依赖的版本，并保留 lock 文件。复用拾知录时，先沿用现有版本与脚本，不必为了套教程重建技术栈。

如果你不需要后台，文章直接用 Markdown 文件维护，选择静态路线会少很多工作。下面涉及数据库、登录和上传的步骤，服务于需要后台的路线。

2. 把这个任务交给开发智能体

请作为主开发者，在当前项目目录直接实施。

先读取 docs/需求说明.md、docs/设计说明.md 和现有文件。
确认当前路径、Git 状态、使用的包管理器与已有改动。
不要覆盖不明文件，不要修改项目外的资料。

先完成最短使用链路：
管理员登录 → 新建一篇文章 → 保存草稿 → 预览 →
发布 → 访客在列表和详情页读到 → 下架后不再公开。

如果需求明确不需要后台，则改为：
新增一个文章文件 → 生成列表与详情 → 构建 → 访客可读。

要求：
1. 真正创建和修改项目文件，安装必要依赖，运行项目并修复错误。
2. 后台路线必须写入持久化数据库，刷新和重启后数据还在。
3. 草稿、私人记录、源文件和密钥在服务端做访问控制。
4. 配好 Git 忽略规则、.env.example 和 README。
5. 先完成最小链路，再逐页补全已确定功能。
6. 每完成一个可运行阶段，报告验证结果并保存代码版本。
7. 更新 HANDOFF.md，写清已完成、运行命令、测试证据和未完成事项。

正常、可逆的本地开发步骤可以直接推进。
购买资源、对外发布和覆盖真实数据，按我另行给出的具体范围执行。
不要只输出代码示例，也不要只给后续计划。

3. 新手怎么检查 AI 有没有真正做

你至少应该看到：

1. 项目目录出现实际代码与配置文件。
2. AI 执行依赖安装，并解决安装问题。
3. 出现真实运行地址，例如 http://localhost:3000/。
4. 你能打开网站、点击按钮，完成上述操作链路。
5. README 写有与你当前项目相符的命令。

如果 AI 只回复「请创建以下文件」，先确认当前使用的是有文件操作能力的智能体环境。没有这些权限，换一句提示词也不会自动获得能力。

4. 命令怎么用

进入项目后，先看 package.json 的 scripts。框架默认只会提供部分命令，不能假设每个项目都有 smoke、typecheck 或 start:standalone。

拾知录当前有这些命令：

npm ci
npm run db:deploy
npm run dev

这是已有 lock 文件、环境配置和初始化流程的项目的示例。首次建站可能先用 npm install 生成依赖锁文件，再按 AI 写好的说明初始化。

新管理员的密码与会话密钥由你在受保护的本地配置中设置。不要照用教程里的演示密码，也不要让 AI 把真实密码写进聊天、Git 提交或说明书。

开发服务器运行时，终端持续占用是正常现象。关闭终端，本地开发网站通常就会停止；后面的服务器托管会解决这个问题。

进入下一步的条件： 你亲自完成一次发布与下架；保存后的内容在刷新与重启后仍然存在。

七、第 4 步：补全页面，用真实文章检查阅读体验

1. 页面按使用顺序补

建议顺序：

1. 文章列表与详情：能找到文章、打开、读完。
2. 首页：说清自己是谁、分享什么，能进入内容。
3. 关于与联系：使用真实资料，确认链接有效。
4. 后台维护：能编辑、预览、发布、下架、处理错误。
5. 工具箱与其他栏目：根据已确认需求增加。
6. 隐私说明、404、加载中、无内容等必要状态。

不要等到最后才用真实文章。长标题、中文代码说明、表格与图片，越早导入越容易发现排版问题。

2. Word、PDF、Markdown 分开处理

Word 的标题最好提前使用「标题 1 / 标题 2 / 标题 3」样式。把普通段落字体放大，不一定能得到正确章节目录。

DOCX 转网页不保证与 Word 逐像素一致；需要固定版式时保留 PDF 更合适。PDF 没书签，就根据实际能力手工维护目录，别要求 AI 猜出可靠的完整章节。

3. 内容发布检查

• 标题、摘要、作者和日期符合实际内容。
• 文档截图不含 API Key、会话、订单、私人联系方式等无意公开的信息。
• 代码复制后的文字与原文一致。
• 图片在未登录窗口里能够正确显示。
• 下载按钮拿到正确文件，外链指向正确地址。
• 修订或撤回内容后，核对网页正文、目录、站内下载和外部文档副本，避免旧内容仍可访问。
• 飞书等外部文档链接，使用未登录窗口检查是否需要额外权限。
• 草稿、下架内容及其关联文件按设定的发布策略处理。
• 演示内容清理前先预览清单，保留真实记录。

飞书链接是否能被所有读者打开，取决于文档本身的分享权限；网站有按钮不能替代这项检查。

本站的 Markdown 下载由数据库中的当前正文生成，修改教程或笔记后会随正文更新。飞书文档是独立副本，需要单独编辑和核验；修改网站正文不会自动更新飞书。

4. 复制给 AI 的阅读与手机验收任务

请用真实内容检查当前网站，而不是只看演示卡片。

分别检查桌面、390px 和 320px 宽度：
长标题、长代码、表格、图片、目录、固定导航、菜单、弹窗和下载入口。
确认整页不会被长内容撑宽，允许代码框或表格内部按需横向滚动。
测试文章目录跳转后标题不被导航遮挡。
点击复制按钮并核对实际剪贴板内容。

使用已登录和未登录两种状态检查。
写入操作使用隔离测试数据，不向真实内容库塞测试文章。
问题先复现，再做局部修复，最后重新验证并保存截图。

进入下一步的条件： 至少 3 篇真实内容可正常阅读，手机上的导航、正文、图片和必要文档功能可用。

八、第 5 步：换一个聊天或工具验收，再修复

验收需要同一份需求和同一版代码。让开发者先写交接单，确认当前目录、Git 提交或未提交变更，再把目录交给验收者。

1. 独立验收提示词

你现在是独立验收者。

请读取 docs/需求说明.md、README.md、HANDOFF.md、
当前源码、Git 状态和本次 diff，然后实际运行验证。
交接单只是开发者自述，核心结论需要运行结果支持。

这一轮先检查、复现和出报告，不修改业务代码。
测试账号、数据库、上传目录和构建目录使用隔离环境。
不要对真实客户、真实文章或正式数据库做写入测试。

请覆盖：
1. 安装、类型检查、lint、生产构建和生产模式启动。
2. 新增 → 草稿 → 预览 → 发布 → 修改 → 下架的真实链路。
3. 保存后刷新与重启，数据仍然存在。
4. 未登录访问后台页面、接口和私人文件，不能获得私人数据。
5. 草稿、下架文章及其封面、图片、附件的访问权限。
6. 重新导入失败时，已保存内容和相关文件保持一致。
7. 从新数据库首次安装，以及从已有数据副本执行迁移。
8. 实际点击页面内链、复制、菜单、目录、下载与外链。
9. 桌面和手机宽度的阅读与交互。
10. 数据库与上传文件成套备份、隔离恢复及失败处理。

按当前项目实际存在的命令执行，不要虚构脚本。
不存在的能力或未执行项请写明。

输出：要求、执行方式、结果、证据、问题严重程度、复现步骤。
最后区分：
本地验收结果 / 部署准备结果 / 尚需真实公网验证的项目。
有阻碍上线的问题时，生成可以交回开发者的修复任务。

不需要每次改一个错字都重复全套验收。首次上线、大改发布链路、上传权限或数据库时使用完整清单；普通改动按受影响范围验证。

2. 修复提示词

请根据下面的验收报告修复当前项目：

【粘贴本轮仍然存在的问题】

先按复现步骤确认问题，再做最小范围修改。
优先处理数据泄露、数据损坏、无法运行和核心功能错误。
保留正常功能、用户已有改动和原始验收要求。
不要通过删除测试、吞掉错误或硬编码返回值使检查变绿。

修完重新执行原先失败的操作，验证相关功能没有回归。
更新 HANDOFF.md，逐项说明证据与剩余限制。

3. 上线前至少检查到这个程度

robots.txt 和 noindex 只是抓取规则，不能当成访问控制。移除一个公开入口，也不等于其接口或附件已经私有。

进入下一步的条件： 没有未解决的严重泄露、数据损坏、无法运行和核心功能缺失问题；其余问题有处理决定和记录。

九、第 6 步：先把代码和数据存好，再准备服务器

1. 代码存档

Git 保存代码版本；远程仓库是另一份代码副本。可以用 GitHub Desktop 或让 AI 帮你检查和提交。

请检查当前项目的 Git 状态与忽略规则。

确认真实 .env、密钥、数据库、uploads、备份、
node_modules 和构建产物没有进入提交。
检查暂存区与历史中是否有明显的敏感文件。

为当前已通过验收的代码保存一个清晰的本地提交。
如果我已经提供远程仓库，报告目标仓库与将上传的文件范围。
不要把真实业务数据当成代码一起推送。

建议新手先使用自己的私有仓库。网站公开与代码仓库是否公开，是两个选择。浏览器运行需要的前端 HTML、CSS、JavaScript 和公开素材仍然可以被访客读取。

如果密钥已经提交过，后补忽略规则不会把它从历史里抹掉。先撤销、轮换相应凭据，再处理历史。

检查发布文件范围时，把实际运行需要的新增代码、数据库迁移和公开素材一并纳入；把截图缓存、临时测试产物和包含私人数据的文件留在发布版本之外。不要因为项目里有大量未提交文件，就直接把整个目录无差别上传。

2. 数据备份

有后台时，至少区分三样：

备份同时固定数据库与上传文件；校验文件引用、数量和完整性；在临时目录恢复并打开验证。把一份受保护副本放到另一台设备或其他存储中。

配置与密钥也要有单独、受保护的恢复安排，且不混入公开仓库。使用加密备份时，解密凭据不要与备份包放在同一公开位置。

拾知录已有 scripts/backup-site.sh，会短暂停止服务固定数据，再校验数据库与媒体。新项目需要实际实现和验证相应脚本，不能只写一句「已经备份」。

3. 一次交付应该包含哪些文件

请 AI 交付：

• 能运行的项目与明确版本。
• 正确的安装、初始化、开发、构建和生产启动命令。
• 无真实秘密的环境变量模板。
• 数据库迁移与上传文件存放说明。
• 管理员初始化、密码与会话管理说明。
• 验收报告、已知限制。
• 服务器部署文件、备份恢复与版本回退步骤。

进入下一步的条件： 即使换一个智能体接手，也能凭这些文件找到正确项目、启动它、验证它。

十、第 7 步：选择适配网站的公网部署路线

1. 先判断你的站是哪一种

本教程下面选择第二条。不要把已有 SQLite 文件和运行时上传直接丢进一个不能持久保存文件的平台，就认为完成了部署。

Next.js 官方支持自托管，并建议使用反向代理处理面向公网的流量；其文档也区分了持久磁盘和短生命周期实例的行为。Next.js 官方自托管说明

2. 地域与备案先确定

主要读者在中国大陆，可以优先比较满足实际需求的大陆云资源；在确定产品时核实它是否符合备案接入条件、需要哪些材料。

使用中国内地服务器对外提供网站服务，需要按实际情况完成适用的 ICP 备案流程。中国香港或海外节点的 ICP 要求不同；其他适用义务仍要按主体、实际用途与当地要求核对。不要把换地域解释成免除所有义务。阿里云备案服务器检查、备案流程 FAQ

站名、主体与实际用途如实填写。代码审查不能保证备案通过，也不能用「付款发生在站外」替代对网站实际用途的判断。

这一阶段可以准备代码、配置、域名实名与材料；中国内地路线要按接入商要求安排测试和开放时机，满足条件后再对外开放。

3. 准备这些信息

域名：【你注册并持有的域名】
服务器厂商与地域：【填写】
服务器系统：【填写发行版与版本】
服务器公网 IPv4：【填写】
SSH 登录方式：【自己配置，私钥不贴入公开文档】
项目远程仓库：【填写】
站点实际用途：【填写】
备案适用情况与进度：【填写】
是否已有文章和上传数据需要迁移：【填写】
代码目录：【例如 /srv/bienberlain】
持久化目录：【例如 /var/lib/bienberlain】
备份位置：【本机目录与异地副本分别写】

新手可以选常见 Linux 发行版并保持一条路线，例如 Ubuntu 24.04 LTS。具体 Node、Nginx 和证书安装命令由 AI 对照该系统官方说明生成。

拾知录原部署方案以小型单机为起点。2 核 2GB 可以作为评估起点；在服务器上构建、导入大文档或运行重动效资源时，需根据实测留出内存和磁盘余量，不能承诺固定规格一定足够。

4. 这张部署结构要看懂

读者的浏览器
    ↓ 正式域名 + HTTPS
服务器的 443 端口
    ↓
Nginx：证书、上传限制、转发请求
    ↓ 本机内部连接
Node 网站程序：127.0.0.1:3000
    ├── 公开页面：只返回已发布内容
    ├── /admin 与管理接口：服务端检查登录与权限
    └── 私有持久化目录
          ├── SQLite 数据库
          └── 上传资源

systemd：服务启动、退出后拉起、开机运行
备份任务：数据库 + 上传文件 → 本机备份 + 异地副本

数据库目录不放在 public 或 Nginx 可直接下载的目录。后台登录页面可以有公网地址，后台数据必须经过真正的服务端授权。

十一、第 8 步：把网站部署到服务器

这部分由 AI 协助执行。你需要在云控制台完成账号、身份与资源准备，并确认具体部署目标。

下面的路径与服务名沿用拾知录。自己的新站可以换名，但应用、环境变量、systemd、Nginx 和备份脚本必须统一。

Linux 命令在服务器终端执行；不要直接粘贴到 Windows PowerShell。Windows 电脑也可以通过 SSH 连接后，在远程 Linux 终端执行。

1. 先让 AI 准备与你服务器匹配的部署包

请为当前网站准备可实际执行的 Linux 部署方案。
先读取源码、package.json、现有部署文档和数据路径实现。

服务器情况：
【粘贴上一章的信息；不要包含私钥、密码或 API Key】

请生成：
1. 对应系统的运行环境安装步骤。
2. 普通服务账号、代码目录、持久化目录及权限。
3. 正式环境变量模板。
4. 首次建库与已有数据迁移两套流程。
5. 生产构建与启动方式。
6. systemd 服务文件。
7. Nginx 反向代理与上传限制。
8. DNS、HTTPS 申请及续期步骤。
9. 数据库和附件成套备份、隔离恢复、更新回退。
10. 可逐项验证的公网验收清单。

先核对所有命令是否真的存在。
指出我需要亲自处理的账号、密钥、域名和备案事项。
不要提前写成「部署成功」；拿到目标环境并实际验证后再记录结果。

2. 核对 SSH 和网络入口

云控制台记录公网 IP，配置自己的 SSH 登录方式。首次连接时通过云控制台核对服务器指纹，确认连的是自己买的实例。

示例：

ssh 你的管理用户名@你的服务器公网IP

网站通常对访客开放 80、443。SSH 管理入口限制为你的授权来源或使用厂商提供的安全管理通道。应用 3000 端口只供服务器内部反代使用，不向公网直接开放。

确认安全组与系统防火墙两层规则。先验证新的登录方式可用，再调整旧入口，避免把自己锁在服务器外。

这一步应看到： 你已经进入正确服务器，可以查到系统版本和 Node 版本。

3. 分开存放代码与运行数据

推荐目录：

/srv/bienberlain                 代码与构建
/var/lib/bienberlain             SQLite 与 uploads
/var/backups/bienberlain         受保护的本机备份

专用账号运行网站程序，授予必要读写权限；系统管理由有 sudo 权限的管理账号处理。不要用开放所有目录权限的方式解决报错。

拉取代码只带项目所需文件。不要把 Mac 上的 node_modules 或 .next 原样当成 Linux 生产包使用，依赖和原生模块可能与系统有关。

这一步应看到： 服务器上存在正确代码版本，数据目录独立于 public 与构建目录。

4. 设置正式环境变量

拾知录的核心示例：

NODE_ENV=production
DATABASE_URL="file:/var/lib/bienberlain/bienberlain.db"
DATA_DIR="/var/lib/bienberlain"
SITE_URL="https://你的正式域名"
ADMIN_SESSION_SECRET="在服务器本地生成并填写足够随机的密钥"
ADMIN_SESSION_HOURS="72"
TRUST_PROXY="1"

这里的会话密钥是占位文字，不能直接拿来运行。上传大小等其他配置参考项目自己的 .env.example。

几点与这个项目直接有关：

• DATABASE_URL 与 DATA_DIR 指向同一套真实数据，生产使用绝对路径。
• SITE_URL 使用最终域名，不能保留 localhost。
• TRUST_PROXY 只有在可信反向代理覆盖客户端 IP 请求头、且应用入口不被绕过时才启用。
• 真实配置文件限制读取权限，排除出 Git。
• AI 开发工具的 API Key 与网站运行配置分开。普通内容站不需要因为「用 AI 写的」就在运行时调用模型。

这一步应看到： 配置项目齐全，工具不输出真实秘密，应用与迁移脚本解析的是同一个数据库路径。

5. 初始化数据库，或迁移已有内容

两种情况分开处理：

全新站点： 安装依赖 → 应用迁移 → 创建自己的管理员 → 构建。不要在正式启动时自动导入演示数据。

已有本地内容： 先固定本地数据库与 uploads 的一致副本 → 受保护地传到服务器 → 放入持久化目录 → 核对归属与权限 → 在副本上验证迁移 → 再按计划应用生产迁移。

SQLite 是本机数据库文件；复制到服务器后，应用要连接服务器上的新位置。不能让公网网站仍依赖开发电脑上的数据库路径。

拾知录对应命令示例：

npm ci
npm run db:deploy
npm run build
npm run start:standalone

管理员创建按项目说明单独完成；如果迁移包含现有管理员，先确认账号策略，避免无意覆盖。

在服务器内部检查：

curl -fsS http://127.0.0.1:3000/api/health

拾知录期望返回的核心状态：

{"ok": true, "database": "up", "schema": "ready"}

其他新站没有这个健康接口时，需要先实现相应检查。HTTP 200 之外，还要看数据库与 schema 状态，并实际请求关键页面。

生产启动需要包含 public、.next/static、PDF 阅读器等必要资源。拾知录的 start:standalone 是项目自定义脚本，负责补齐相关内容；新建 Next.js 项目默认没有这条命令。

这一步应看到： 构建成功，服务可在服务器内部访问，关键页面与静态资源正常，原文章和附件都在。

6. 用 systemd 托管服务

在首次手动验证后，结束那份手动服务，再交由 systemd 托管，避免两个进程争抢 3000 端口。

以下是需要由 AI 结合实际环境填写的配置骨架：

[Unit]
Description=Bienberlain Website
After=network.target

[Service]
Type=simple
User=bienberlain
Group=bienberlain
WorkingDirectory=/srv/bienberlain
Environment=NODE_ENV=production
Environment=HOSTNAME=127.0.0.1
Environment=PORT=3000
ExecStart=/usr/bin/npm run start:standalone
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

这里假定 npm 路径为 /usr/bin/npm、服务账号已创建、启动脚本会加载受保护的项目配置。使用其他安装方式时，先检查实际可执行路径和服务账号环境。

由管理账号安装服务文件、重新加载并启用服务：

sudo systemctl daemon-reload
sudo systemctl enable --now bienberlain
sudo systemctl status bienberlain

日志可以通过以下方式查看：

sudo journalctl -u bienberlain -n 100 --no-pager

配置日志保留与磁盘上限。使用文件日志时增加轮转。

这一步应看到： 服务处于 active，关闭 SSH 后仍能运行，重新启动服务后文章与文件仍在。

7. 域名解析到服务器

在域名服务商的 DNS 控制台添加记录：

是否使用 www 由你决定；两个入口都使用时，让一个统一跳转到另一个。只有服务器确实配置 IPv6 并开放对应服务时，才添加 AAAA。

DNS 的修改入口取决于域名当前使用的权威 DNS 服务商。记录保存后等缓存更新，再解析检查；没有固定「几分钟必好」的保证。

这一步应看到： 根域名解析到正确 IP，而不是仅仅在控制台显示「已保存」。

8. 配置 Nginx 和 HTTPS

先让 Nginx 按域名转发到 127.0.0.1:3000。证书签发前，按所选证书工具要求准备 HTTP 验证路径或 DNS 验证；拿到证书后再引用真实证书文件，启用 HTTPS，并把普通 HTTP 跳转过去。

反向代理的关键内容示例，放在对应的 server 配置内：

client_max_body_size 60m;

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 180s;
}

60m 是为本例约 50MB 文档上传保留的请求余量，实际需要与应用限制匹配。示例假设 Nginx 直接接收访客连接；前面再加 CDN 或其他代理时，重新核对可信 IP 传递策略。

让 AI 根据当前 Nginx 和证书工具生成完整配置，核对域名、证书文件、续期任务与上传行为，然后执行：

sudo nginx -t
sudo systemctl reload nginx

这一步应看到： 正式 HTTPS 地址无证书警告；HTTP 正确跳转；证书包含正在访问的域名；续期方式已经验证。

9. 配置定时备份和恢复

让备份任务定期运行，检查上次执行结果，设置保留周期与磁盘告警，再把副本同步到独立存储。

至少做一次隔离恢复：在临时目录还原数据库与 uploads，核对文章、文件、权限与完整性。恢复演练不直接覆盖正式数据库。

这一步应看到： 备份批次有清单和校验结果；故意模拟缺文件、打包失败时，不会误报成功；可以从一个备份批次恢复出可读内容。

十二、第 9 步：用外网完成最终验收

本地检查通过之后，这张表必须在真实公网地址上重新执行。没有目标环境时，保留为空，不能提前打勾。

可以对外分享的完成标准： 公网核心流程通过；严重权限与数据问题解决；未覆盖浏览器、剩余告警和其他限制已经如实记录。

能打开公网地址，不代表搜索引擎已经收录。提交站点地图后仍需等待和观察，也不能承诺一定排名。

可复制的公网验收任务

现在对已部署的真实网站做公网验收。

正式地址：【https://你的正式域名】
对应代码版本：【填写】
目标环境：【填写服务器与部署方式，不含秘密】

请实际检查：
域名解析、HTTP→HTTPS、证书、关键页面和静态资源、
真实文档、登录与退出、匿名权限、发布与下架、
重启持久化、sitemap 与 robots、备份任务和证书续期。

发布和写入测试只使用已约定的测试内容，不修改真实私人资料。
记录每项执行环境、方法、时间和结果。
没有访问权限或工具能力的项目明确标记未验证，不推测为通过。
需要我用手机外网或亲自登录的地方，给出明确操作步骤。

最后分别列出：已验证、失败、未验证、需要处理的事项。

十三、第 10 步：上线之后怎么更新

1. 只发文章

有后台：登录 → 新建或编辑 → 保存草稿 → 预览 → 检查图片与链接 → 发布 → 无痕窗口复查。

静态站：把文章文件交给 AI → 本地预览 → 保存代码版本 → 重新构建部署 → 公网复查。

文章修订也要看发布策略：编辑是否立即改线上，还是保留独立草稿等待发布？让系统行为与界面提示一致。

2. 改功能与样式

每次按这个顺序：

描述这次具体要改什么
    ↓
确认正在使用的目录、分支和线上版本
    ↓
备份数据库与上传文件；保存当前代码
    ↓
本地修改与受影响范围验证
    ↓
生产构建
    ↓
部署新版本；需要时执行已验证的迁移
    ↓
重启与公网复查
    ↓
保留可用的回退方案与发布记录

不要让 AI 直接在生产数据上试验。包含数据迁移的更新，需要先拿旧数据副本验证。

3. 出问题怎么回退

纯界面或代码问题，可以恢复上一个可用代码版本再构建运行。

如果数据库已经发生不兼容迁移，代码回退可能不够。先保留当前数据，再评估恢复哪个数据库与 uploads 批次、会影响哪些新内容，最后按恢复计划操作。

「Git 有历史」和「可以恢复整站数据」是两件都需要落实的事。

4. 定期看这些

• 网站是否可用，证书、域名与服务器何时续费。
• 备份是否按时成功，异地副本是否可恢复。
• 磁盘、上传文件和日志是否持续增长。
• 依赖是否有相关安全更新，需要更新时先验证兼容性。
• 文章步骤、工具链接和外部文档分享权限是否变化。

十四、卡住时，对照这张表

遇到问题时，可以使用这段通用任务：

当前现象：【描述看到的问题】
复现操作：【写从哪一页开始、点了什么】
预期结果：【你本来希望看到什么】
实际结果：【现在出现什么】
相关错误：【如有，提供已隐藏秘密的原始错误】

请先复现、收集证据并定位根因，再做最小修改。
不要删功能、跳过验证、清空真实数据库或重建整个项目。
修完重新执行相同操作，并说明验证结果。

十五、第一次动手，可以直接从这段开始

把下面整段发给已经打开正确项目目录的 Codex、Claude Code 或 DeepSeek Harness。

我没有编程经验，希望你协助我做一个能真正上线的个人网站。

网站名称：【填写】
网站用途：【填写】
目标读者：【填写】
第一版内容：【填写】
更新方式：【后台发布 / 文章文件】
视觉参考：【说明并附图】
是否需要 PDF、Word 导入：【填写】
是否保存私人数据：【填写；没有就写没有】
主要读者地区：【填写】
站点年度费用上限：【填写；不确定就先不购买】

请先确认当前项目目录、已有文件、Git 状态和可用工具。
我希望沿着以下步骤推进：

1. 把需求、公开边界和验收条件写入 docs/需求说明.md。
2. 选择能实际部署、容易维护的技术方案，记录数据持久化要求。
3. 给出首页与文章页的静态布局，让我集中反馈一次。
4. 开始实际开发：写文件、安装依赖、启动、测试、修复。
5. 先做「内容新增→预览→发布→访客阅读→下架」的完整链路。
6. 补齐确定的页面、手机适配与真实内容，再添加必要动效。
7. 自检并生成独立验收任务，由另一个聊天或工具复核。
8. 准备服务器配置、域名、HTTPS、备份恢复和公网验收。
9. 在已确认的目标资源和授权范围内协助部署；未部署项如实保留。
10. 交付运行说明、交接单、实际测试结果与后续更新方法。

工作要求：
保留已有成果，不随意换框架，不扩展成商城或大型系统。
正常可逆的本地开发直接推进；有重要缺失信息再问我。
私人数据、密钥与上传资源在服务端做正确控制。
测试使用独立数据，不修改真实客户或文章。
不要只输出示例代码；实际执行，直到这一阶段的交付条件满足。
需要我登录、填写秘密、处理身份材料或购买资源时，给出具体步骤。

请先用简短中文告诉我：
项目路径是什么、第一阶段要完成什么、我现在需要提供什么。
然后开始完成不依赖这些补充信息的工作。

附录：本案例依据与如何复用

1. 本次复盘使用的项目材料

这份文档是复盘与操作指南，没有在写作过程中重新执行整站完整测试，也没有执行服务器购买或公网发布。

2. 哪些经验可以直接复用

需求写清、参考图对应具体元素、分阶段交付、真实内容提前验证、独立验收、唯一主项目、Git 存档、数据库与文件成套备份、公网单独验收，这些适用于多数个人网站。

Next.js、SQLite、PDF 阅读器、玻璃场景和私有客户后台，是拾知录的具体选择。你可以按自己的需要取用，不必全部照搬。

3. 哪些内容每次执行前要再核对

智能体界面与模型配置、Node 和框架支持版本、云产品价格、服务器规格、证书工具、备案要求和第三方文档链接，都可能变化。按执行当天的官方资料与实际项目确认。

完成这套工作流后，你应当持有：项目代码、文章和文件数据、自己控制的域名与服务器账号、可用的备份，以及一套自己能继续使用的发布与更新方法。