面向客户和代理的源码交接清单

源码交接应达到的目标

源码交接是项目从“代理能运行的东西”变为“客户能拥有的东西”的时刻。没有清晰的交接，常见问题会很快出现：应用只在一个笔记本上能构建，生产环境依赖某个没人能找到的密钥，或一次小改动变成几天的猜测工作。

任何源码交接清单的目标很简单：转移后，客户能在不需要代理随叫随到的情况下构建、运行并部署产品。这并不意味着“永不支持”。意思是基础流程是可复现且有文档记录的，下一个接手的人可以有把握地继续工作。

交付物的范围应该明确。至少，完整的交接通常包括：

• 完整仓库（包括部署文件和迁移脚本）
• 能在干净机器上运行的安装文档
• 访问移交（账号、权限以及系统所在位置）
• 常规操作手册（部署、回滚、备份、日志）
• 客户可参考的最终“已知良好”版本标签或快照

范围与内容同样重要。有些交接只涵盖某个环境（例如仅生产）。也有的包括 dev、staging 与 production，且每个环境有独立设置与流程。如果不明确列出包含哪些环境，人们会有不同假设，而这正是引发宕机的原因。

一个实用的成功定义是验证测试：未曾构建过该应用的人可以导出代码（例如从像 Koder.ai 这样的平台），按照文档设置环境变量，运行迁移，构建并部署到约定的环境。

本清单聚焦于技术就绪：环境变量、密钥轮换、数据库迁移、部署脚本和构建验证。不涵盖法律条款、合同、知识产权条款或支付争议。这些也很重要，但应放在另一个协议里。

导出前：就归属与时间达成一致

干净的交接始于导出前。如果能就谁拥有什么以及何时拥有达成一致，就能避免临时惊喜，比如部署中断、托管费用未付或访问丢失。

设定交接日期与短暂冻结期

选定交接日期并定义冻结窗口（通常 24–72 小时），在此期间仅允许紧急修复入库。这样能保证导出的代码与运行系统保持同步。如果在冻结期内需要热修复，要把改动详细记录，确保它包含在最终导出中。

明确账号与计费归属

决定谁将负责 DNS、云托管与任何付费服务的归属。这不仅是纸面工作：如果计费仍挂在代理名下，服务日后可能被无预警暂停。

可以把它写得具体：

• 指定 DNS、托管和邮箱的账户所有者
• 确认从交接日起谁支付每笔账单
• 决定是转移现有账户还是在客户名下重新创建
• 记录每个供应商的支持联系人

用通俗语言把这些写下来，便于双方遵循。

列出环境及运行位置

就有哪些环境达成一致（local、staging、production）以及每个环境的运行位置。说明 staging 是独立服务器、独立数据库，还是仅通过特性开关区分。如果你使用过像 Koder.ai 这样的平台，也要确认哪些内容托管在平台上，哪些预期在导出后运行在客户基础设施里。

提前收集访问权限

不要等到最后一天再请求访问。确保合适的人能访问所需资源：仓库、CI、托管、数据库和邮件供应商。

还要就最终验收测试与签字流程达成一致。例如：“客户能从干净机器构建、运行迁移、部署到 staging 并通过烟雾测试，然后双方书面签字确认。”

仓库与文档基础项

一份好的源码交接清单从一个新团队能在几分钟内打开并理解的仓库开始。确认包含什么（应用代码、配置模板、脚本）以及哪些是刻意排除的（真实密钥、私钥、大型生成文件）。如果有排除项，说明它们存放在哪里且谁负责。

保持结构可预测。建议顶层文件夹清晰，比如 frontend/、backend/、mobile/、infra/、scripts/、docs/。如果是 monorepo，解释各部分如何关联以及如何运行每一项。

README 应该能被没有参与构建的人使用。它应覆盖前置条件以及最快上手的步骤，避免猜测。

必须记录的内容（最低要求）

在 README 中包含简短且以人为对象的部分，回答：

• 本仓库包含什么及其功能简介（一段话）
• 前置条件与精确版本（运行时、包管理器、Docker 等）
• 一键本地启动步骤（以及“成功”是什么样子）
• 如何运行测试并构建生产产物
• 关键文档的位置：架构说明、迁移记录、部署说明

用通俗语言补充简单的架构说明：谁跟谁通信、为何这样设计。一两句话通常够用。示例：“React 前端调用 Go API。API 读写 PostgreSQL。后台任务作为独立 worker 进程运行。”

最后，包含一个版本化的变更日志或交接发布说明。可以是 CHANGELOG.md，或一个短的“交接发布说明”文件，说明确切的 commit/tag、交付内容以及已知问题。

如果代码是从像 Koder.ai 这样的平台注册并导出的，请注明生成的项目类型（web、服务端、移动）、预期使用的工具链（例如 React、Go、PostgreSQL、Flutter），以及客户端应使用的支持的操作系统/工具版本以复现构建。

环境变量：清单与文档化

环境变量常常是“可运行的应用”在交接后失败的根源。好的交接把它们当成产品的一部分，而不是事后考虑。

先写出一份无须猜测即可跟随的清单。用通俗语言，包含示例值格式（不要放真实密钥）。如果某变量可选，要说明缺失时的后果与默认值。

一个简单的呈现方式：

• 变量名、控制内容及示例格式
• 必需或可选，以及默认行为
• 设置位置（CI、托管面板、本地 .env 文件）
• 哪些环境需要不同的值（dev、staging、production）
• 谁负责变更（客户、代理或共享）

明确标出环境差异。例如，staging 可能指向测试库与沙箱支付提供商，而 production 使用真实服务。还要指出必须在各系统间匹配的值，如回调 URL、允许的来源或移动应用包标识符。

记录每个值当前所在位置。许多团队把值分散在不同地方：本地 .env 文件用于开发，CI 变量用于构建，托管设置用于运行时。如果你使用像 Koder.ai 这样的导出，请包含 .env.example 并简短说明哪些变量必须在首次构建前填写。

最后，证明仓库内没有隐藏的密钥。不要只检查当前文件，也要检查提交历史，寻找意外泄露的密钥、旧的 .env 文件或样例配置中复制的凭证。

具体示例：React 前端与 Go API 可能需要 API_BASE_URL（前端）和后端的 DATABASE_URL 以及 JWT_SIGNING_KEY。如果 staging 使用不同域名，写明两套值并说明在哪里修改，避免新团队把 staging 设置错发到 production。

密钥轮换：安全转移并验证可行性

交接不完整，除非客户控制应用所需的每个凭证。这意味着要轮换密钥，而不是简单地共享。如果代理（或前承包商）仍然持有可用密钥，就有一扇无法审计的后门。

先做完整清单，别只记数据库密码。包括第三方 API key、OAuth 客户端密钥、Webhook 签名密钥、JWT 签名键、SMTP 凭证、存储访问密钥，以及 CI 中的任何“临时”令牌。

轮换当天的简单清单：

• 列出每个密钥、它能访问什么以及当前设置位置（本地 env、CI、托管面板、vault）
• 在客户账户下创建新凭证，并为每项指定负责人（某人 + 团队邮箱）
• 更新应用配置以使用新值，先在 staging 或测试环境部署
• 在确认新凭证正常工作后立即撤销旧凭证
• 记录具体的轮换步骤，使下次轮换变得无聊且迅速

轮换后证明一切正常。做真实用户流的测试，而不要只看日志。

关注依赖密钥的流程：

• 登录、注册、重置密码、令牌刷新
• 支付、发送邮件与文件上传
• Webhook（签名验证与重试机制）
• 调用外部 API 的后台任务或定时任务
• 触及特权端点的管理操作

示例：如果你从 Koder.ai 导出了项目且应用使用支付提供商与邮件服务，轮换这两个 key、重新部署，然后发起一笔小额测试交易并发送测试邮件。仅在这些测试成功后撤销代理所有的密钥。

最后，记录未来密钥的存放地（vault、CI 变量或托管设置）、谁能修改，以及轮换失败时如何安全回滚。

数据库迁移与数据处理

交接看起来“完成”时，数据库往往是首先出问题的部分。把迁移与数据当成独立的产品：版本化、可复现并经过测试。

先写下当前数据库版本及迁移文件在仓库的位置。要具体：文件夹路径、命名规则及最新迁移的 ID（或时间戳）。如果使用 PostgreSQL（Go 后端常见），还要说明需要的扩展。

应记录的内容（以便他人能运行）

包含简短运行手册，回答：

• 哪个命令运行迁移，执行顺序（创建数据库、应用迁移、然后导入 seed）
• 各环境差异（本地、staging、production），包括任何“安全模式”标志
• 迁移是否在部署时自动运行或需手动执行，以及谁被允许运行它们
• Seed 数据策略：无、仅演示或最少必需记录（管理员用户、默认设置）
• 回滚计划：哪些可以逆转、哪些不能（例如会破坏性删除列）

回滚要诚实。有些变更只能用备份恢复。把这一点用通俗语言说明，并配上备份步骤（发布前快照并验证恢复流程）。

在交接完成前，尽可能在生产数据副本上运行迁移。这能发现慢查询、缺失索引或“空数据上能跑、真实数据上失败”的问题。一次真实的测试是：导出代码、设置环境变量、恢复匿名化的数据转储，然后从头应用迁移。这个操作能验证交接清单中很大一部分内容。

如果应用是在像 Koder.ai 这样的平台注册并导出，务必再次确认迁移文件与任何 seed 脚本包含在导出中，且仍被后端启动流程正确引用。

构建与 CI：让过程可复现

交接只有在别人能在干净机器上从头重建应用时才算完成。交接清单应包含确切的构建命令、所需版本与期望产物（例如：“web bundle 在 /dist”、“API 二进制名”、“Flutter APK 的位置”）。

写下你实际使用的工具和包管理器，而不是你以为用的。典型栈可能包括用于 React 的 Node.js（npm 或 pnpm）、服务端的 Go 工具链、本地环境的 PostgreSQL 客户端工具，以及移动端的 Flutter SDK。

使依赖安装可预测。确认锁文件已提交（package-lock.json、pnpm-lock.yaml、go.sum、pubspec.lock），并在新电脑或干净容器上做一次全新安装以证明可行。

记录 CI 的每一步，以便能迁移到其它 CI 提供方：

• 安装依赖（使用锁文件）
• 运行测试与 lint 检查
• 构建输出（web bundle、服务端二进制、移动端构建）
• 生成工件（zip、Docker 镜像、发布包）
• 存储日志与构建元数据（版本、commit、日期）

把构建时配置与运行时配置区分开。构建时配置会被编译进产物（例如 API 基址嵌入到 web bundle），运行时配置在应用启动时注入（比如数据库 URL、API key 与特性开关）。混淆这两者是“CI 上可跑但部署后失败”的常见原因。

提供简单的本地验证步骤。即便是一短串命令也足够：

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

如果你是从像 Koder.ai 这样的平台导出，包含任何生成的 CI 文件或用于部署的构建预设，使客户能在平台外复现相同构建。

部署脚本与发布流程

交接不应止于“这是仓库”。还要说明代码如何变成运行服务，以及谁按下发布按钮。

先记录当前的部署方式：完全手动（有人在服务器上运行命令）、CI 驱动（流水线构建并部署）或通过托管平台。说明配置存放位置，以及存在的环境（dev、staging、production）。

让发布步骤可复现。如果流程依赖某人记住 12 条命令，把它们封装成脚本并说明所需权限。

部署包应包含的内容

给客户足够的信息以便第一天就能部署：

• 构建与运行命令（以及确切的 Node、Go、Flutter 等版本）
• 部署脚本（shell 脚本、Makefile 目标或流水线配置）
• 所需访问：云账号角色、容器镜像仓库、DNS、数据库管理员权限
• 环境设置说明：env vars 存放位置及各环境差异
• 发布命名规则：tag/release 及如何识别正在运行的版本

就停机期预期达成一致。如果需要“零停机”，说明实际采用的方法（蓝绿部署、滚动发布、迁移时只读窗口）。若可接受停机，定义明确时间窗口。

静态资源与缓存是常见失败点。说明资产如何构建与提供，何时清理缓存，以及是否使用 CDN。

可执行的回滚

回滚应是短小且经过测试的步骤，且与 tag 或 release ID 关联。例如：部署之前的 tag、按需恢复数据库快照并使缓存失效。

如果应用是在 Koder.ai 上创建后导出的，提及最后已知良好快照与确切导出版本，便于客户快速将代码与可用发布对应起来。

步骤化：导出后验证构建

验证是检验交接是否真实的时刻。目标很简单：陌生人能拿到导出的代码、完成设置并在没有猜测的情况下运行相同的应用。

开始前记录“正确”应是什么样：运行应用的版本、当前 commit/tag（如有）、以及一两个关键屏幕或 API 响应用于比对。如果导出来自像 Koder.ai 的平台，记下快照或导出时间戳以证明测试的是最新状态。

1. 确认导出与生产一致：检查提交历史、发布说明或构建元数据。比对运行中应用的可见版本字符串或某个小行为（例如特定设置或 UI 标签）。
2. 设置环境变量与密钥：创建目标环境配置（本地与 staging），使用提供的 env 变量清单并确保仓库中没有硬编码值。
3. 安装依赖并运行测试：做一次干净安装（无缓存的 node_modules/vendor 文件夹）。按文档运行单元测试与 lint。
4. 运行迁移并本地启动：启动数据库，按顺序应用迁移并启动应用。确认应用能读写基本数据且无待应用的迁移。
5. 部署到 staging、烟雾测试，然后晋级：使用计划在生产中使用的脚本/流水线部署。仅在 staging 符合预期后再晋级。

烟雾测试保持简短并围绕风险点：

• 登录/登出（或创建测试用户）
• 一个核心工作流的端到端（创建-编辑-保存）
• 如适用，测试一个邮件/ webhook/ 支付回调
• 基本错误处理（错误输入、缺失记录）
• 日志中无重复崩溃或密钥相关错误

若有失败，记录确切命令、错误输出与所用环境变量。这些细节在所有权更替时能节省数小时排查时间。

常见交接错误及避免方法

把“代码就是全部”的想法放弃是避免交接变成火线处理的最快方法。好的交接清单关注那些决定客户能否真正运行并修改应用的小而无聊的细节。

导致大多数交接问题的错误

大多数问题来自以下几种模式：

• 未轮换密钥，代理的旧密码、API key 或云令牌在移交后仍然可用。
• 环境变量不完整，因为有些值仅存在于 CI 或托管仪表盘，而未出现在仓库中。
• 忘记一时性的生产改动，例如临时热修、手工数据库修改或直接在服务器上设置的配置开关。
• 数据库迁移在本地可运行但在生产失败，原因是缺少权限、缺失扩展或模式归属问题。
• 没有回滚计划，或者没有被标记的发布（release note），当首次部署出问题时无法回退。

如何在不拖延数周的情况下预防它们

把轮换与访问清理设为有日程的任务，而不是“有空再做”。设定日期，届时移除代理账号、重新生成服务密钥，并由客户确认仅凭自己的凭证能部署。

对环境变量，从三个地方做简单清单：仓库、CI 系统与托管 UI。然后在新机器或容器上通过干净构建验证它们。

对迁移，用将用于生产部署的相同数据库角色做测试。如果生产需要提升权限（例如启用某个扩展），把这些步骤写清楚并明确归属。

一个现实例子：从 Koder.ai 导出项目后，客户部署成功但后台任务失败，因为某个队列 URL 只在托管仪表盘中设置。一次简单的环境变量审计就能发现问题。把它与标记的发布和文档化的回滚（例如“重新部署 tag v1.8.2 并恢复最近快照”）配合，就能避免停机。

最终清单、示例与下一步

如果你只保留本源码交接清单中的一页内容，就保留这一页。目标很简单：干净克隆在新机器上能运行，使用新的密钥，并能让数据库安全前进。

快速检查（从干净克隆执行）

在从未见过该项目的笔记本上或干净容器/VM 中运行这些检查。那是发现缺失文件、隐藏假设与旧凭证的最快方式。

• 从头构建：安装依赖、运行测试（如有）、并在无人工修改下产出发布构建。
• 配置生效：设置文档中列出的环境变量，确认应用能在新配置或 env 下启动。
• 密钥已轮换：验证应用在新密钥下运行，撤销旧密钥并确认无异常。
• 迁移可顺利运行：使用空数据库运行迁移，再启动应用并触发一个基础流程。
• 部署路径真实可走：运行部署脚本或 CI 工作流一次，确认产物与预期一致。

一个简单的交接示例

某代理交接了 React 前端、Go API 与 PostgreSQL 数据库。客户团队克隆仓库，将提供的 .env.example 复制为真实 env 并创建新的数据库、邮件提供商与第三方 API 凭证。他们运行 go test（或约定的测试命令）、构建 React 应用、对新的 Postgres 实例应用迁移并启动两个服务。最后，他们使用文档化脚本部署并确认相同的 commit 今后可复现构建。

下一步

保持交接简短且有人负责。30–60 分钟的演示通常胜过冗长文档。

• 安排一次演示并记录决策（谁负责部署、密钥与数据库变更）。
• 指定一个生产访问负责人和一名备份。
• 确认并标记最终“验收构建”的 commit hash。
• 如果你在 Koder.ai 上构建并导出源代码，导出后在首次客户部署时使用快照与回滚以降低风险。