<!-- gitea-wiki-mirror:start -->
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Deployment-Template
wiki_url: https://git.ilapage.cn/OPC/goauto/wiki/Deployment-Template.-
wiki_revision: b1b1b343917e66288f4282bc6b3b90ea4ff3cca0
synchronized_at: 2026-09-04T11:30:41Z
<!-- gitea-wiki-mirror:end -->

# 部署文档模板

> 本页是内部维护模板，不描述 GoAuto 当前真实生产部署。真实部署拓扑、域名、运行账号、目录、端口、凭据来源和回滚方式经过确认后，复制本页建立 `Deployment-and-Operations`；删除说明文字和占位值后再交付。不得把本地 Windows Supervisor 配置或 `server/docker-compose.yml` 直接宣称为生产方案。

## 本页用途

让维护者能够从已确认的干净环境完成首次部署、日常运维、健康检查、升级和回滚。每条命令必须写明执行位置、权限前提和预期结果。

## 安全边界

- 只记录配置项名称和安全来源，不记录密码、Token、Cookie、私钥、证书内容、PDD 账号、生产数据库地址、个人数据或生产数据。
- 发布、权限、数据库迁移、删除数据和不可逆操作必须有独立工单、备份与人工确认。
- GoAuto 永不执行付款；部署步骤不得引入支付能力或绕过现有高风险门禁。
- 对外服务必须使用 HTTPS；内部监听、反向代理、证书与防火墙边界按真实环境填写。

## 服务概览

| 项目 | 已确认内容 |
|---|---|
| 环境名称与用途 | `<填写>` |
| 目标提交或版本 | `<填写>` |
| 代码部署目录 | `<填写>` |
| 运行账号 | `<填写>` |
| Admin API 托管方式 | `<填写>` |
| Admin UI 托管方式 | `<填写>` |
| 内部监听地址 | `<填写>` |
| 对外域名与路径 | `<填写>` |
| MySQL/外部依赖 | `<填写名称与来源，不写敏感值>` |
| 日志位置 | `<填写>` |

## 环境要求

逐项写明操作系统、Go、Node/pnpm、MySQL、反向代理、进程托管工具和 Android 构建环境的版本要求、检查命令与预期结果。只保留部署端实际需要的组件。

## 首次部署

### 1. 准备账号与目录

记录最小权限运行账号、代码/配置/日志目录、属主和权限检查。服务账号不得复用个人高权限账号。

### 2. 取得代码并绑定版本

记录仓库来源、目标分支/标签/完整提交哈希及校验命令。部署记录必须保存实际提交哈希，不使用“最新版”。

### 3. 安装依赖与构建

分别记录服务端、管理端和需要交付的 Android 构建命令；每一步写明预期产物与失败停止条件。

### 4. 落位配置

列出 `GOAUTO_CONFIG`、数据库 DSN、端口、HTTPS、对象存储、SYB、AI Provider 等实际启用配置的安全来源和文件权限。不得把敏感值写入 Git、Wiki、工单或日志。

### 5. 数据库备份与迁移

> 数据库迁移属于高风险操作。必须先确认备份可恢复、迁移版本、影响范围和回退条件，再由独立授权执行。

记录迁移前检查、备份、迁移命令、表结构/版本验证和失败停止方式；不得通过修改已执行迁移版本号强制重跑。

## 进程托管与反向代理

按已确认的 Windows Supervisor、Linux supervisor/systemd、容器或其他真实方式填写：

- 进程名称、工作目录、启动/停止/重启命令；
- 自动重启、优雅停止、日志轮转和依赖启动顺序；
- nginx 或其他接入层配置、WebSocket/超时/静态资源规则；
- 配置语法检查和无中断重载命令；
- HTTPS 证书来源与续期检查，不记录证书内容或私钥。

## 配置与凭据来源

| 配置项 | 用途 | 安全来源 | 是否敏感 | 更新后动作 |
|---|---|---|---|---|
| `<名称>` | `<用途>` | `<密码库条目或受控配置路径>` | 是 / 否 | `<重启/重载/无需动作>` |

## 日常运维

用表格记录状态、启动、停止、重启、日志、配置重载、磁盘/数据库检查的命令与预期结果。不得把高风险动作包装成无确认的一键命令。

## 健康检查

每次部署、重启和回滚后至少验证：

- 进程状态稳定；
- Admin API 健康检查返回预期状态；
- Admin UI 能加载且 API 地址正确；
- WebSocket/Agent 连接按授权环境验证；
- 日志没有新增异常堆栈或敏感信息；
- 数据库迁移版本与目标提交相符。

任何一项不符合都不视为部署成功。

## 升级与回滚

### 升级

记录升级前提交、备份、目标提交、依赖安装、构建、迁移、进程重启和全量健康检查顺序。

### 回滚

记录可安全回滚的代码版本、产物、配置和数据条件。已执行的数据迁移不能假定可由切回代码自动撤销；不向后兼容时停止并使用已验证的备份恢复流程。

### 备份与恢复

记录备份对象、频率、位置、保留期、加密/访问权限、恢复步骤和最近一次恢复演练结果。

## 已知限制

明确记录尚未验证的真实回滚、多机部署、故障转移、容量、高并发、证书续期和灾难恢复能力；不得留空或用模板占位值宣称已经支持。