DEPLOYMENT

该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。

参考资料DOCXv1.0

参考资料DOCX下载原文件

> 该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。

DEPLOYMENT.md

项目部署、启动、更新、回滚与恢复说明

文档版本： v1.0文档状态：持续维护最后更新： 2026-07-27文档性质：项目部署与运行事实源适用对象：项目负责人、AI开发助手、部署AI、运维人员、后续接手开发人员

0. 本文件是什么

本文件用于回答：

这个项目离开当前开发环境以后，怎么重新跑起来？

包括：

新电脑怎么启动

开发环境怎么安装

前端怎么运行

后端怎么运行

数据库怎么连接

环境变量怎么配置

Production Build怎么执行

服务器怎么部署

域名怎么连接

HTTPS怎么配置

反向代理怎么配置

项目怎么更新

更新失败怎么回滚

数据怎么备份

数据怎么恢复

日志在哪里

服务挂了怎么检查

新AI接手时怎么判断部署状态

1. 本文件不负责什么

项目当前状态

查看：

PROJECT_STATUS.md

系统模块结构

查看：

ARCHITECTURE.md

参数在哪里修改

查看：

CONFIGURATION.md

Bug

查看：

BUG_TRACKER.md

版本变化

查看：

CHANGELOG.md

AI开发规则

查看：

AI_START_HERE.mdAI_RULES/

2. 部署最高原则

项目必须尽量实现：

拿到代码↓准备运行环境↓安装依赖↓填写环境变量↓连接数据库↓执行必要迁移↓Production Build↓启动服务↓Health Check↓核心功能验证↓完成部署

不得依赖：

“之前某个AI知道怎么启动”“这台电脑以前装过什么”“服务器里面好像有个文件”“之前手工改过一个地方”

这些隐性知识。

3. 部署的定义

项目真正“部署成功”不是：

代码上传服务器

而是至少满足：

服务成功运行+前端正常打开+后端正常响应+数据库正常连接+核心API正常+登录正常+权限正常+静态资源正常+HTTPS正常+日志可用+异常可定位+存在备份/恢复方案

4. 部署环境分类

本项目至少区分：

Development开发环境Production生产环境

如项目规模增加，可增加：

Test测试环境Staging预发布环境

5. 环境禁止混用

禁止出现：

开发环境↓直接连接生产数据库

或者：

生产网站↓调用localhost API

或者：

测试账号↓成为生产管理员

6. 当前真实部署状态

当前：

【待真实项目扫描和运行验证】

需要确认：

□ 当前开发环境可以启动□ 当前Production Build可以成功□ 当前Production服务可以启动□ 当前服务器环境可以运行□ 当前数据库可以正常连接□ 当前域名正常□ 当前HTTPS正常□ 当前反向代理正常□ 当前API正常□ 当前登录正常□ 当前管理员系统正常□ 当前日志可查看□ 当前备份存在□ 当前恢复方案可执行

7. 当前技术栈

必须由AI扫描真实项目后补充。

前端

框架：

【待扫描】

版本：

【待扫描】

包管理器：

【待扫描】

Build工具：

【待扫描】

后端

框架：

【待扫描】

版本：

【待扫描】

运行环境：

【待扫描】

数据库

类型：

【待确认】

版本：

【待确认】

Web服务器 / 反向代理

【待确认】

例如可能是：

NginxApacheCloudflare云平台网关其他

8. 当前部署方式

当前项目实际部署方式：

【待确认】

可能属于：

静态前端部署前后端分离单体应用Docker云平台托管虚拟机部署Serverless其他

9. 部署架构

真实项目扫描后补齐。

目标形式例如：

用户浏览器 │ ▼ 域名 │ ▼ HTTPS │ ▼反向代理 / 网关 │ ├─────────────┐ ▼ ▼Frontend /api │ ▼ Backend │ ┌────┼────┐ ▼ ▼ ▼ DB AI Storage

实际：

【待确认】

10. 新机器部署前准备

拿到一台新的电脑或服务器后：

不要立刻运行代码。

先检查：

操作系统CPU架构内存磁盘运行时版本包管理器数据库网络端口权限时区

11. 操作系统

当前支持环境：

【待确认】

例如：

WindowsLinuxmacOS

生产推荐系统：

【待确认】

12. Node.js版本

如果项目使用Node.js：

当前要求：

【待扫描 package.json / .nvmrc / 文档】

推荐明确：

Node.js XX

不应只写：

“安装Node就行”

因为不同版本可能导致：

依赖安装失败Build失败API行为变化

13. Python版本

如果项目使用Python：

当前：

【待扫描】

应记录：

Python版本虚拟环境方式依赖安装命令

14. 其他运行环境

如存在：

JavaPHPGo.NETRust其他

记录：

【待扫描】

15. 包管理器

当前前端包管理器：

【待扫描】

只能根据Lock文件和项目真实配置判断。

例如：

npmpnpmyarn

不要同时：

npm installpnpm installyarn

混着使用。

16. Lock文件

当前：

【待扫描】

例如：

package-lock.jsonpnpm-lock.yamlyarn.lock

生产安装应尊重Lock文件。

17. 后端依赖

当前依赖文件：

【待扫描】

例如：

package.jsonrequirements.txtpyproject.tomlpom.xmlgo.mod

18. 获取项目代码

当前项目代码来源：

【待确认】

例如：

Git仓库本地目录压缩包云平台项目

正式推荐：

版本控制系统作为代码事实源。

19. 项目根目录

当前：

【待确认】

部署文档不得写：

D:\某人的电脑\AAA…

作为生产必要路径。

20. 禁止依赖个人绝对路径

生产环境不得依赖：

C:\Users\某人...D:\项目...桌面...下载...

如果当前存在：

进入：

BUG_TRACKER.md

21. 安装依赖

实际命令：

【待扫描】

例如可能是：

npm ci

或：

pnpm install –frozen-lockfile

生产环境优先使用：

能够严格遵循锁文件的安装方式。

22. 为什么不建议随便 npm install

如果已有Lock文件：

普通安装可能改变依赖树。

正式部署应尽量保证：

开发测试使用的依赖=生产部署依赖

23. 环境变量

部署前必须检查：

.env.example

如不存在：

应建立。

生产所需全部变量必须可以从：

.env.exampleCONFIGURATION.md

找到名称和用途。

24. 生产环境变量清单

真实扫描后填写：

变量	用途	是否必填	是否敏感	影响服务
待扫描

25. 环境变量原则

生产Secret必须来自：

服务器环境变量云平台Secret Manager安全配置系统

不得来自：

前端源码公开Git仓库READMECHANGELOGCONFIGURATION.md

26. .env文件权限

如果生产环境使用本地 .env：

必须限制访问权限。

不得允许：

所有系统用户可读取。

27. .env不得直接公开

例如：

网站静态目录中绝不能出现：

/.env

可以被浏览器下载。

28. Secret部署后检查

上线前检查：

JWT_SECRETDATABASE_PASSWORDAI_API_KEYACCESS_KEYPRIVATE_KEY第三方Secret

均未进入前端Bundle。

29. 数据库准备

如果项目使用数据库：

部署前确认：

数据库已安装 / 已创建数据库服务运行数据库用户存在权限正确数据库名称正确网络可达配置正确

30. 开发数据库与生产数据库

必须明确：

Development DatabaseProduction Database

实际：

【待确认】

禁止部署时：

误把测试库作为生产库。

31. 数据库账号权限

应用使用的数据库账号：

应遵守最小权限。

一般不应无理由拥有：

创建系统用户管理整个数据库服务器访问其他数据库

32. 数据库Migration

当前迁移体系：

【待扫描】

例如：

Prisma MigrationAlembicDjango MigrationTypeORMSQL脚本其他

33. Migration执行规则

正式部署前：

先确认：

是否需要迁移迁移是否向后兼容是否涉及删字段是否涉及改类型是否涉及大量数据是否已经备份

34. 禁止盲目自动迁移

如果迁移可能破坏数据：

不得仅因为服务启动就自动执行。

需要明确：

Migration Required: Yes / No

35. Migration命令

当前：

【待扫描】

36. Seed数据

项目是否需要初始化数据：

【待确认】

例如：

默认配置系统角色基础权限初始化管理员

37. 初始化管理员

如果存在默认管理员：

必须重点确认安全。

禁止生产环境永久使用：

admin123456

等默认账号密码。

38. 首次管理员建立方式

当前：

【待确认】

应明确：

命令后台初始化邀请数据库Seed其他

不能依赖：

AI手工修改数据库。

39. 前端开发启动

当前命令：

【待扫描】

例如：

npm run dev

开发访问地址：

【待扫描】

40. 后端开发启动

当前命令：

【待扫描】

监听地址：

【待扫描】

端口：

【待扫描】

41. 本地联调

开发状态下确认：

Frontend↓API↓Backend↓Database

全部通。

检查：

CORSProxyCookieToken端口

42. Development验证

本地开发环境至少执行：

□ 前端启动成功□ 后端启动成功□ 首页打开□ API正常□ 数据库正常□ 登录正常□ 管理员登录正常（如存在）□ Console无关键Error

43. Production Build

这是部署前最重要步骤之一。

当前Build命令：

【待扫描】

例如：

npm run build

但必须以项目真实配置为准。

44. Production Build成功标准

必须满足：

命令成功退出无阻断错误输出目录存在核心静态资源存在未包含明显开发Mock未包含Secret资源路径正确

45. Warning处理

Build Warning不能直接：

全部忽略。

需要区分：

无害Warning依赖弃用Bundle过大类型问题安全风险未来兼容风险

46. Build输出目录

当前：

【待扫描】

例如：

dist/build/.next/

47. Build产物检查

检查：

HTMLJSCSS图片SVG字体Source Map

是否完整。

48. Source Map

生产是否生成：

【待确认】

如公开Source Map：

需要评估是否暴露：

源码结构

内部路径

实现细节。

49. Production运行方式

当前：

【待确认】

例如：

静态文件服务Node ServerPython ServerDocker云平台Runtime

50. 前端部署方式

当前：

【待确认】

如果属于静态前端：

记录：

51. 后端部署方式

当前：

【待确认】

记录：

启动命令：服务目录：运行用户：监听端口：环境变量：日志：

52. 服务运行用户

生产服务原则上：

不应无理由使用：

rootAdministrator

运行。

应使用：

最小权限服务账号。

53. 服务后台运行

当前方式：

【待确认】

可能：

systemdPM2DockerSupervisor云平台托管其他

54. 服务守护

服务器重启后：

应用应能够合理恢复。

当前：

【待确认】

55. systemd

如使用：

服务文件：

【待扫描】

应记录：

Service NameWorking DirectoryExecStartEnvironmentUserRestart Policy

56. PM2

如使用：

配置文件：

【待扫描】

应记录：

App NameScriptEnvironmentInstancesRestart

57. Docker

是否使用：

【待确认】

如果存在：

Dockerfiledocker-compose.yml

记录真实路径。

58. Docker Build

命令：

【待扫描】

59. Docker Run

命令：

【待扫描】

60. Docker Secret

不得：

把Secret直接写入Dockerfile。

应使用：

EnvironmentSecretRuntime配置

61. Docker Volume

如果数据库、上传、日志需要持久化：

必须明确Volume。

否则容器删除后：

数据可能一起消失。

62. Docker Healthcheck

当前：

【待确认】

63. 前端与后端端口

实际扫描后维护：

服务	内部端口	对外端口	配置位置
Frontend	待确认	待确认	待扫描
Backend	待确认	待确认	待扫描
Database	待确认	不建议公网开放	待扫描

64. 数据库端口

生产数据库原则上：

不应无必要直接开放公网。

如果公网暴露：

必须检查：

防火墙白名单认证加密账号权限

65. 域名

当前正式域名：

【待确认】

DNS服务：

【待确认】

66. DNS

部署后确认：

A记录AAAA记录（如有）CNAME解析目标TTL

正确。

67. HTTPS

正式公网环境应使用：

HTTPS

当前证书方式：

【待确认】

68. SSL证书

记录：

证书来源：证书部署位置：续期方式：过期监控：

不得把：

私钥内容

写入本文件。

69. HTTP → HTTPS

当前：

【待确认】

应确认HTTP访问是否合理重定向到HTTPS。

70. Mixed Content

HTTPS页面不能继续加载：

http://

接口、字体、图片、脚本。

部署后必须检查。

71. 反向代理

当前：

【待确认】

如果使用Nginx：

配置路径：

【待扫描】

72. Nginx职责

可能包括：

HTTPS静态文件API ProxyWebSocket上传大小超时缓存安全Header

真实情况：

【待确认】

73. API反向代理

目标可能是：

https://example.com/api/*

转发到：

Backend

实际：

【待确认】

74. 同域API

如果可行：

生产环境推荐：

Frontendhttps://example.comAPIhttps://example.com/api

减少复杂跨域问题。

实际是否采用：

【待确认】

75. CORS

如果前后端不同域：

必须检查：

Allowed OriginCredentialsMethodsHeaders

禁止简单：

解决所有问题。

76. Cookie与域名

如果认证使用Cookie：

修改域名时同步检查：

DomainSecureSameSitePath

77. SPA刷新

如果项目是SPA：

必须测试：

直接打开 /直接打开 /xxx浏览器刷新 /xxx

不能出现：

首页正常，

子页面一刷新404。

78. SPA fallback

如需要：

服务器应将未知前端路由合理指向：

index.html

但不能把：

/api/不存在

也返回index.html。

79. 静态资源路径

生产部署后检查：

JSCSS图片字体SVG视频

不能因：

Base Path

域名

子目录

发生404。

80. 字体部署

特别检查：

字体文件路径CORSMIME缓存Fallback

因为字体系统属于当前项目重要视觉能力。

81. 上传文件

如果支持上传：

必须明确：

上传目录访问方式权限最大大小备份生命周期

82. 上传文件不能放临时目录

否则服务器重启或清理后：

用户文件可能消失。

83. 上传文件权限

用户A上传的私人文件：

用户B不能通过猜URL访问。

84. 对象存储

如果使用：

OBSOSSCOSS3

记录：

Provider：Bucket：配置变量名：访问策略：CDN：

真实Secret不记录。

85. 第三方服务部署检查

所有第三方服务部署时确认：

API KeyBase URL回调URL白名单域名HTTPS超时配额

86. AI服务部署

如果项目调用AI：

必须确认：

ProviderModelBase URLAPI KeyTimeoutToken限制Rate Limit并发Fallback

87. AI Key

只能位于：

后端。

生产前必须检查：

前端Build中不存在真实Key。

88. AI费用保护

正式部署不得无限制调用。

应确认：

单用户调用次数单次Token上限每日额度并发上限异常重试次数

89. 登录部署验证

部署后必须真实测试：

正确登录错误密码退出刷新登录状态过期状态受保护页面

90. 管理员部署验证

必须真实测试：

管理员登录管理员接口管理员页面退出普通用户访问管理员页面普通用户调用管理员API

91. 权限部署验证

至少测试：

GuestUserAdmin

如存在Super Admin：

同时测试。

92. 数据库部署验证

上线后检查：

数据库连接读取合法写入事务迁移状态连接池

禁止用生产环境执行危险测试。

93. Health Check

正式长期运行的后端建议存在：

/health

或类似。

当前：

【待确认】

94. Health Check建议检查

应用运行数据库连接必要服务

不建议Health接口泄露：

Secret数据库密码服务器路径内部配置

95. Readiness与Liveness

规模增加后可以区分：

Liveness程序活着Readiness程序是否准备好接受请求

当前：

【待确认】

96. 日志

上线后至少需要知道：

服务日志在哪里？

当前：

【待确认】

97. 日志类型

建议至少包含：

ApplicationErrorAccessLoginAdmin Audit

98. 日志查看方法

实际命令：

【待确认】

例如可能是：

journalctlpm2 logsdocker logs日志文件

必须按真实部署方式补充。

99. 错误排查第一入口

网站异常时优先：

浏览器Console↓Network↓反向代理日志↓Backend日志↓数据库状态↓第三方服务

不要第一反应：

重新安装整个项目。

100. 日志安全

生产日志禁止记录：

密码完整TokenJWT SecretAPI KeyPrivate Key数据库密码

101. 日志轮转

当前：

【待确认】

必须避免日志：

无限增长。

最终占满服务器硬盘。

102. 磁盘

部署后关注：

Build日志上传缓存数据库备份

占用。

103. 临时文件

当前临时目录：

【待扫描】

应有：

清理机制。

104. 缓存

当前：

【待确认】

部署时可能包含：

Browser CacheNginx CacheCDNService WorkerServer Cache

105. Service Worker

如果存在：

部署新版本时必须考虑：

旧缓存。

否则：

服务器已经更新，

用户仍然看到旧网站。

106. 缓存版本更新

当前机制：

【待确认】

107. CDN

当前：

【待确认】

如使用CDN：

发布后可能需要：

刷新缓存版本化资源等待TTL

108. 更新部署

正式更新版本建议流程：

确认新版本↓查看CHANGELOG↓查看Upgrade Notes↓确认数据库变化↓备份↓部署新代码↓安装依赖↓执行Migration（如需要）↓Build↓启动↓Health Check↓核心流程测试↓完成发布

109. 更新前必须查看CHANGELOG

重点看：

DatabaseConfigDependenciesDeploymentSecurityBreaking ChangeUpgrade Notes

110. 更新前备份

涉及以下任一内容：

数据库用户上传配置认证体系重大依赖服务器结构

更新前建议备份。

111. 更新前检查当前版本

记录：

当前版本：目标版本：

防止：

不知道从哪个版本升级到哪个版本。

112. 更新前检查工作目录

如果生产服务器使用Git：

确认没有：

服务器现场手改未提交文件临时补丁

否则更新可能覆盖。

113. 禁止生产服务器直接作为开发环境

不要在生产服务器：

随手修改代码。

正确流程：

开发环境修改↓测试↓Build↓发布

114. 滚动更新

如果未来项目规模增加：

可使用：

Blue-GreenRollingCanary

等策略。

当前：

不强制。

避免过度工程化。

115. 停机更新

如果当前小型项目：

允许合理短暂停机。

但必须明确：

何时停如何恢复失败如何回滚

116. 回滚

每一次重要生产更新：

原则上应具备：

回到上一可用版本

的方法。

117. 回滚不是只回代码

如果更新同时修改了：

DatabaseConfigUploadCache

回滚必须考虑这些数据变化。

118. 回滚前确认

□ 上一版本代码存在□ 上一版本依赖可安装□ 上一版本配置存在□ 数据库兼容□ 文件数据兼容□ Secret仍有效

119. 代码回滚

当前方式：

【待确认】

例如：

Git TagCommitRelease包服务器备份

120. 数据库回滚

当前：

【待确认】

部分数据库Migration：

可能无法安全自动回滚。

这种情况：

必须依靠：

备份恢复。

121. 配置回滚

重要配置更新前：

应保留上一版本配置。

Secret除外：

不能把旧Secret长期明文存档。

122. 回滚后必须再次验证

首页API登录管理员数据库核心功能

不能只看到进程启动：

就认为回滚成功。

123. 备份体系

备份至少分：

代码数据库用户上传配置

124. 代码备份

125. 数据库备份

当前方式：

【待确认】

需要记录：

备份命令：备份位置：备份频率：保留时间：恢复方式：

126. 用户上传备份

当前：

【待确认】

如果用户文件只存在服务器本地磁盘：

服务器故障可能导致数据丢失。

127. 配置备份

需要备份：

配置结构。

但Secret应使用安全方式管理。

128. 备份频率

当前：

【待定义】

具体频率应根据：

数据变化频率数据重要程度恢复成本

确定。

129. 备份保留策略

不要永远只保留：

一个最新备份。

否则：

最新备份已经损坏时，

无旧版本可恢复。

130. 备份位置

备份最好不要只存在：

与生产服务完全同一块磁盘。

否则服务器硬盘损坏：

生产和备份一起没。

131. 恢复测试

最重要的一条：

没有测试过恢复的备份，不应被认为是可靠备份。

132. 数据库恢复

实际步骤：

【待当前数据库类型确认后填写】

133. 用户文件恢复

当前：

【待确认】

134. 配置恢复

当前：

【待确认】

135. 灾难恢复顺序

严重故障时参考：

确认事故范围↓停止继续破坏↓保存日志和现场↓判断是否数据受损↓选择修复或回滚↓恢复数据库/文件↓恢复应用↓测试↓重新开放服务

136. 禁止事故发生后第一时间删除现场

例如：

服务器出错：

不要直接：

删除日志重装服务器清空数据库重新部署

应该先保留：

排障证据。

137. 故障分类

A. 前端故障

例如：

白屏资源404JS Error布局崩溃

B. API故障

例如：

500404CORS超时

C. 数据库故障

例如：

连接失败Migration失败连接数耗尽

D. 认证故障

例如：

所有用户无法登录Cookie失效JWT配置错误

E. 服务器故障

例如：

进程退出磁盘满内存不足

F. 第三方服务

例如：

AI服务不可用存储不可用邮件失败

138. 首页打不开排查

顺序：

域名是否解析2. HTTPS是否正常3. 服务器是否在线4. 反向代理是否运行5. Frontend Build是否存在6. 静态资源是否4047. 浏览器Console

139. 页面打开但接口全失败

检查：

Backend进程API Base URL反向代理端口CORSHTTPS认证

140. 本地正常服务器异常

重点检查：

环境变量绝对路径大小写Node/Python版本API地址端口文件权限Production Build数据库地址

141. Windows与Linux差异

特别注意：

Linux路径：

区分大小写

本地Windows可能：

Image.png

和：

image.png

都能意外工作。

Linux可能直接404。

142. 路径分隔符

避免业务代码绑定：

等单一平台路径行为。

优先使用：

语言/框架提供的路径API。

143. 文件权限

生产环境需要检查：

源码读取权限上传目录写权限日志目录写权限配置文件读取权限

但不要给：

过大的777权限

作为默认修复。

144. 端口被占用

如果服务启动失败：

先检查：

端口是否占用。

不要立即：

随机换另一个端口。

因为：

ProxyCORSAPI Client防火墙

可能依赖原端口。

145. 防火墙

生产环境需要确认：

真正需要对外开放的端口。

通常：

80443

可能对外。

Backend内部端口：

视架构决定是否只允许本机/内网访问。

数据库：

原则上不直接公网开放。

146. 云安全组

如果使用云服务器：

检查：

安全组。

不要因为访问失败：

直接开放：

192.0.2.10/0所有端口

147. SSH/RDP

服务器管理入口也需要安全。

不属于网站代码本身，

但属于部署安全。

148. 管理后台网络保护

如果管理后台非常敏感：

未来可以考虑：

额外身份验证IP限制VPN安全网关

根据实际规模决定。

生产反向代理/后端应检查：

CSPHSTSX-Content-Type-OptionsReferrer-PolicyFrame限制Permissions-Policy

实际：

【待审计】

150. Rate Limit

生产部署后确认：

登录限流管理员登录限流普通API限流上传限流AI限流

真实生效。

不能只看配置文件。

151. 请求大小限制

可能同时存在：

浏览器后端Nginx云平台

多层限制。

例如上传失败时：

需要确定是哪一层拒绝。

152. 超时

可能包括：

Client TimeoutReverse Proxy TimeoutBackend TimeoutDatabase TimeoutAI Timeout

应避免：

无限等待。

153. 重试

部署后的网络重试：

必须有限次数。

避免：

第三方服务挂了以后：

自己的服务器疯狂重试把自己打死。

154. 安全扫描

正式上线前至少执行：

Secret扫描依赖漏洞扫描硬编码扫描权限检查暴露接口检查

155. 前端Build Secret扫描

特别检查Build产物是否包含：

API KeyJWT SecretDATABASE_URL内部服务器地址管理员密码

156. Debug

生产环境必须确认：

危险Debug关闭

包括可能的：

Debug接口开发工具页面详细堆栈测试后门万能认证

157. Mock

Production不得继续依赖：

Mock LoginMock UserMock APIMock Database

冒充真实功能。

158. 404

部署后测试：

不存在页面

应显示合理404。

159. 403

无权限：

应返回合理403或等价处理。

不能：

返回管理员数据。

160. 500

生产500错误：

用户看到：

合理提示。

服务器日志：

记录具体错误。

用户不能看到：

Stack TraceSQL服务器绝对路径Secret

161. 429

被限流时：

前端应该合理处理。

不能无限自动重试。

162. 性能部署检查

上线后检查：

首屏静态资源大小API响应图片字体重复请求缓存

163. 大文件

生产服务器不要无意托管：

原始设计素材PSD临时ZIP备份文件数据库Dump

在公网目录。

164. 备份文件暴露

特别检查是否存在：

backup.zipdatabase.sql.env.bak

可以从网站下载。

如有：

严重风险。

165. Git目录暴露

正式网站根目录不得让外部访问：

.git/

内部内容。

166. 源码暴露

静态服务器根目录不要错误指向：

整个项目源码目录。

应只暴露：

真正公开的Build产物/静态目录。

167. 管理员接口

不能因为前端没有链接：

就认为接口隐藏。

生产后需要直接测试：

普通用户无法访问。

168. API文档

如果生产存在：

Swagger

OpenAPI Explorer

Debug API Docs

需要确认：

是否应该公开。

169. 数据库初始化失败

如果部署时表不存在：

不要让生产请求自动随机创建结构。

应通过可控Migration。

170. 时区

部署后检查：

服务器数据库应用前端

时间是否一致。

特别是：

日志Token过期计划任务创建时间

171. UTF-8

生产环境确认：

源码HTMLAPI数据库日志

编码正常。

防止：

中文乱码。

172. 计划任务

如果存在：

CronSchedulerBackground Job

部署时必须单独确认是否启动。

不能只部署Web服务。

173. 定时任务重复执行

如果部署多个Backend实例：

必须注意：

同一个Scheduler是否会被多实例重复执行。

当前：

【待确认】

174. Queue

如存在任务队列：

需要记录：

Queue服务WorkerBroker启动方式监控

当前：

【待确认】

175. Redis

如存在：

【待确认】

需要记录：

用途：

SessionCacheQueueRate Limit

以及持久化要求。

176. 服务启动顺序

真实架构确认后填写。

例如：

Database↓Redis↓Backend↓Frontend / Proxy

当前：

【待确认】

177. 服务停止顺序

考虑：

停止新请求完成关键任务关闭Backend释放数据库停止依赖

避免直接：

强杀进程。

178. 优雅关闭

Backend应处理：

SIGTERMSIGINT

或对应环境关闭事件。

当前：

【待确认】

179. 监控

当前：

【待确认】

未来可监控：

服务是否在线错误率API延迟CPU内存磁盘数据库AI费用异常登录

180. 告警

关键问题应有告警能力。

例如：

服务挂了磁盘快满数据库无法连接5xx暴增管理员异常登录

当前：

【待确认】

181. 当前小型项目原则

不要为了“专业”一次性建立：

几十套企业级基础设施。

当前优先：

能部署能恢复能排错能备份安全底线正常

再逐渐增加监控和自动化。

182. 手工部署的最低标准

即使暂时没有CI/CD：

也必须有明确：

部署步骤版本备份Build测试回滚

183. CI/CD

当前：

【待确认】

未来目标：

代码提交↓自动Lint↓自动Test↓Build↓Security Scan↓Deployment↓Health Check

184. 部署阻断

自动流程未来应阻止：

Build失败测试失败P0安全问题Secret泄露重大依赖漏洞

进入生产。

185. 首次部署流程

真实项目完善后：

在这里填写唯一正式流程。

当前模板：

STEP 1获取项目代码STEP 2安装所需运行环境STEP 3安装依赖STEP 4复制 .env.example 为对应环境配置STEP 5填写生产环境变量STEP 6准备数据库STEP 7执行数据库MigrationSTEP 8执行Production BuildSTEP 9启动BackendSTEP 10配置FrontendSTEP 11配置Reverse ProxySTEP 12配置Domain / HTTPSSTEP 13执行Health CheckSTEP 14执行核心功能验收STEP 15检查日志STEP 16确认备份STEP 17完成上线

186. 正式部署具体命令

⚠️ 必须扫描当前真实技术栈后填写。

安装依赖：【待确认】数据库迁移：【待确认】前端Build：【待确认】后端Build：【待确认】Backend启动：【待确认】Frontend部署：【待确认】服务重启：【待确认】日志查看：【待确认】

187. 不允许根据模板直接执行

以上：

npmsystemctlpm2docker

等均不得在未确认项目实际技术栈时盲目执行。

188. 部署后验收

每次正式部署后：

执行：

网站

□ 首页打开□ 页面跳转□ 静态资源□ 字体□ 图片□ 404

API

□ 核心接口□ 401□ 403□ 404□ 429□ 500处理

用户

□ 注册（如有）□ 登录□ 用户中心□ 修改数据□ 退出

管理员

□ 管理员登录□ 管理页面□ 管理接口□ 审计日志□ 普通用户无法越权

数据

□ 数据库连接□ 数据读取□ 合法写入□ 数据没有意外丢失

安全

□ Secret无暴露□ HTTPS□ CORS□ 限流□ 管理权限□ Debug关闭

189. Production Smoke Test

每次上线建议执行快速冒烟测试：

首页↓登录↓核心功能↓API↓管理员↓退出

用于快速确认：

生产没有彻底炸掉。

190. 全量回归与Smoke Test区别

Smoke Test：

快速确认核心系统活着。

Regression Test：

全面确认更新没有破坏旧功能。

重大版本：

二者都需要。

191. 生产部署报告

每次正式发布完成后记录：

部署版本：部署日期：部署环境：执行人/AI：Build结果：Migration：服务状态：Health Check：Smoke Test：异常：回滚是否需要：最终状态：

192. 部署状态只能使用

✅ DEPLOYED & VERIFIED⚠️ DEPLOYED WITH UNVERIFIED ITEMS❌ DEPLOYMENT FAILED↩ ROLLED BACK

193. 部署失败

失败时：

不要硬继续后续步骤。

应记录：

失败步骤：错误：当前生产状态：是否影响旧版本：是否需要回滚：

194. 半部署状态

例如：

Frontend更新成功Backend失败

属于危险状态。

不能报告：

“部署基本完成”。

应立即判断：

继续修复

或

回滚。

195. 数据库迁移失败

优先：

停止继续部署。

检查：

是否部分执行是否影响数据是否可回滚是否恢复备份

196. Build失败

Production Build失败：

当前版本：

不能上线。

即使：

npm run dev

正常。

197. Health Check失败

服务进程存在：

不等于系统正常。

Health失败：

需要查：

数据库配置依赖外部服务

198. 服务启动但首页404

检查：

Frontend Build静态目录Nginx rootBase PathSPA fallback

199. 登录部署后失效

检查：

API域名Cookie DomainSecureSameSiteHTTPSJWT SecretSession StoreProxy Headers

200. 管理后台部署后失效

检查：

Admin RouteAdmin APIPermissionAuthProxyStatic Build

201. 文件上传本地正常生产失败

检查：

Nginx上传限制Backend限制目录权限磁盘对象存储请求超时

202. AI本地正常生产失败

检查：

AI_API_KEY模型名网络访问Base URL代理超时余额/配额Rate Limit

203. 数据库本地正常生产失败

检查：

DATABASE_URL网络白名单端口SSL账号权限Migration

204. 服务器重启后网站消失

检查是否：

服务没有自动启动。

需要：

守护进程或云平台自动恢复。

205. 磁盘满

检查：

日志上传备份Docker ImageCache数据库

206. 内存不足

检查：

Memory LeakAI请求并发大型Build过多Worker数据库

207. CPU过高

检查：

死循环高频请求爬虫恶意用户重任务AI处理无缓存查询

208. 请求暴增

生产必须考虑：

Rate LimitCloud FirewallReverse Proxy应用级限制

209. 异常用户

部署后安全措施应能记录：

大量错误登录大量404高频API大量上传管理员异常登录

210. 生产数据操作原则

任何生产环境数据修改：

默认谨慎。

AI不得因为：

“修一下数据”

直接批量执行不可逆操作。

211. 生产数据库禁止测试破坏性行为

例如：

DROPTRUNCATE批量DELETE攻击Payload测试

应使用：

测试环境。

212. 本地保障

如果项目支持本地数据：

必须记录：

存储在哪里怎么备份怎么迁移怎么恢复

当前：

【待确认】

213. 浏览器本地数据

如使用：

LocalStorageIndexedDBService Worker

升级时考虑：

旧数据结构兼容。

214. 数据迁移

前端本地存储结构变化：

也可能需要Migration。

不要只关注数据库。

215. 版本兼容

每次发布应判断：

旧前端 + 新后端新前端 + 旧后端

短时间混合是否安全。

尤其CDN/浏览器缓存存在时。

216. API版本

如果未来产生不兼容API：

建议考虑：

/api/v1/api/v2

不是现在必须做。

根据项目规模决定。

217. Maintenance Mode

未来必要时可建立：

维护模式

用于：

数据库重大迁移。

当前：

【待确认】

218. 部署文档必须由真实运行验证

本文件中任何命令：

只有实际执行成功后：

才能标记：

✅ VERIFIED

219. 命令状态

建议使用：

✅ 已实际验证🔎 根据代码确认但未执行❓ 待确认❌ 当前失败

220. 新机器验证

一个成熟部署文档最终应该通过：

一台没有本项目历史环境的新机器测试。

如果只能：

老电脑能跑，

说明文档和环境仍有隐藏依赖。

221. 干净部署验证

标准目标：

新环境↓项目代码↓文档↓环境变量↓安装依赖↓Build↓运行

成功。

222. 部署文档不能依赖作者本人

即使项目负责人半年后：

完全忘记怎么部署，

看本文件也应该能重新完成。

223. AI接管部署任务

任何AI开始部署前：

必须先读取：

AI_START_HERE.mdPROJECT_STATUS.mdARCHITECTURE.mdCONFIGURATION.mdBUG_TRACKER.mdCHANGELOG.mdDEPLOYMENT.mdAI_RULES/06_RELEASE_OPERATIONS_RULES.mdAI_RULES/04_SECURITY_RULES.mdAI_RULES/05_TESTING_RULES.md

224. 部署前AI必须确认

□ 当前任务确实是部署/更新□ 目标环境明确□ 当前版本明确□ 目标版本明确□ Production Build通过□ P0为0□ 阻断P1为0□ 环境变量已明确□ 数据库变化已确认□ 备份已考虑□ 回滚方式明确

225. AI不得在部署过程中擅自重构

部署阶段目标：

稳定上线

不是：

顺便重写系统

如果发现架构问题：

记录Bug/技术债。

除非它确实阻断部署。

226. AI不得为了部署成功关闭安全机制

例如：

CORS失败：

不能直接全部开放。

认证失败：

不能删除认证。

证书问题：

不能长期退回HTTP。

数据库权限问题：

不能把数据库改为公网匿名访问。

227. AI不得删除数据换取启动成功

例如：

Migration失败：

不能直接：

删数据库重新建

除非明确：

这是空测试数据库

且得到授权。

228. 部署失败也属于结果

如果部署无法完成：

必须如实：

❌ DEPLOYMENT FAILED

而不是：

“基本完成”。

229. 无法验证

例如没有：

服务器权限域名数据库API Key

必须写：

❓ 无法验证

不要假设：

生产环境会正常。

230. 上线前阻断清单

任何以下情况存在：

默认不得正式上线：

P0 Bug核心P1未修Production Build失败用户登录失败管理员严重权限问题Secret暴露数据库连接不稳定生产API错误重大数据风险无法恢复的危险Migration

231. 上线前高优先确认

□ API Base URL不是localhost□ Production数据库不是测试库□ Secret未进入Frontend□ Debug关闭□ Mock关闭□ HTTPS正常□ 普通用户无法访问Admin API□ Rate Limit生效□ 500不暴露内部信息□ Backup存在

232. 当前项目上线状态

依据当前已有信息：

🔴 尚不能仅凭现有文档判定正式可上线

原因：

仍需真实验证：

Production BuildBackendDatabaseAuthAdminAPISecurityDeployment

233. 部署成熟度分级

LEVEL 0

只能在原开发电脑运行。

LEVEL 1

换电脑按手工步骤可运行。

LEVEL 2

生产服务器可稳定部署。

LEVEL 3

具有：

Build日志备份回滚

LEVEL 4

具有：

自动测试CI自动部署健康检查监控

LEVEL 5

具有成熟：

灰度自动回滚监控告警灾难恢复

当前项目级别：

【待真实评估】

234. 当前阶段目标

当前不需要立刻追求：

LEVEL 5。

优先达到：

LEVEL 2 → LEVEL 3

即：

能稳定部署、能看日志、能备份、能恢复、能回滚。

235. 部署快速导航

真实扫描后必须补齐：

我想做什么	去哪里/执行什么
安装依赖	待补
启动前端Dev	待补
启动后端Dev	待补
Build前端	待补
Build后端	待补
设置环境变量	待补
数据库Migration	待补
启动生产服务	待补
重启生产服务	待补
查看日志	待补
查看Health	待补
备份数据库	待补
恢复数据库	待补
回滚版本	待补

236. 项目负责人简化版部署说明

完成真实扫描后：

本节必须写成完全非技术人员也能看懂的版本。

例如：

【网站启动】1. 打开 xxx2. 执行 xxx3. 看到 xxx 代表成功—【网站打不开】先检查 xxx—【查看错误】打开 xxx—【备份】执行 xxx—【恢复】执行 xxx

237. 部署事故记录

如果生产部署失败或造成服务中断：

应进入：

BUG_TRACKER.md

严重事故未来可建立：

INCIDENT-XXXX

238. 部署变化记录

任何重要部署方式变化：

必须写入：

CHANGELOG.md

例如：

从直接端口访问迁移到Nginx HTTPS反向代理。

239. 配置变化

部署需要新增环境变量：

更新：

CONFIGURATION.md.env.example

240. 架构变化

如果部署架构变为：

FrontendBackendRedisWorkerDatabase

等：

更新：

ARCHITECTURE.md

241. 项目状态变化

首次Production部署成功后：

更新：

PROJECT_STATUS.md

不能：

部署已经成功，

状态文档还写：

“未验证”。

242. DEPLOYMENT更新规则

以下变化必须更新本文件：

运行环境变化启动命令变化Build命令变化数据库变化Migration变化服务器变化部署方式变化域名变化反向代理变化HTTPS变化日志方式变化备份方式变化回滚方式变化Docker变化CI/CD变化

243. 以下一般无需更新

页面文案小型UI调整普通业务Bug不影响部署的组件变化

244. AI首次完善本文件任务

当AI拥有真实项目访问权限后：

执行：

STEP 1读取package/依赖文件STEP 2识别运行环境版本STEP 3识别Dev启动命令STEP 4识别Build命令STEP 5识别Production启动方式STEP 6识别.env体系STEP 7识别数据库STEP 8识别MigrationSTEP 9识别Proxy/NginxSTEP 10识别DockerSTEP 11识别日志STEP 12识别BackupSTEP 13识别Health CheckSTEP 14识别CI/CDSTEP 15实际执行能够安全执行的部署验证STEP 16补齐本文件所有能确认字段

245. 本轮如果只是完善文档

禁止：

更换服务器修改数据库执行生产Migration更换域名重置Secret重构部署结构删除旧服务

只：

调查记录验证

246. 如果发现当前部署流程不可复现

建立：

DEPLOYMENT / DOCUMENTATION

类型Bug。

例如：

只有原电脑能运行，没有依赖版本记录。

属于真实维护风险。

247. 如果发现Production Build失败

建立至少：

P1 BUILD

问题。

248. 如果发现Secret暴露

建立：

SECURITY

问题。

并立即提示需要轮换。

249. 如果发现生产数据库无备份

根据项目重要性：

记录为：

DATA / DEPLOYMENT

风险。

250. 最终部署目标

项目最终应达到：

换电脑能启动换AI能接手换服务器能部署更新失败能回滚服务器故障能恢复出现Bug能看日志数据损坏有备份配置变化有说明

251. 项目真正完成上线的定义

不是：

“网站在我电脑能打开。”

而是：

任何符合条件的新环境，都可以按照本项目文件完成部署，并且生产运行状态可验证、可维护、可恢复。

252. 当前下一步

创建本文件后：

下一项建议建立：

.env.example

它负责把：

项目运行到底需要哪些环境变量

变成机器和AI都能直接识别的配置入口。

END

本文件是：

项目部署、运行、更新、回滚、备份与恢复的主要事实源。

所有：

【待扫描】【待确认】

内容，

必须根据：

真实代码

真实配置

真实环境

真实运行结果

补充。

未经实际验证：

不得将部署状态写成成功。

敏感配置：

只记录名称与用途，

永远不得记录真实Secret。