4.9 KiB
4.9 KiB
OPS 本地开发与验收部署说明
1. 文档目标
本文区分本地开发、联调验收和 Linux/麒麟部署三类场景，避免把模板 README 直接作为交付部署手册。
当前仓库尚未保留实际 server/ 和 web/ 工程。后续实际工程创建后，应在对应目录补充更细的运行说明。
2. 场景边界
| 场景 | 目标 | 主要使用者 | 命令口径 |
|---|---|---|---|
| 本地开发 | 开发、调试、单元测试、接口联调 | 开发工程师 | Windows PowerShell |
| 联调验收 | 连接真实后端 API，准备演示数据和证据 | 交付工程师、测试人员 | Windows PowerShell 为主 |
| 生产或验收部署 | 在 Linux/麒麟内网环境部署服务 | 部署工程师 | 本文只写步骤和检查项，不写 Linux 命令示例 |
3. 本地开发目录
| 目录 | 职责 | 状态 |
|---|---|---|
server/ |
实际后端工程，基于 templates/server_sample/ 初始化后继续改造 |
尚未创建 |
web/ |
实际前端工程，基于 templates/front_sample/standard 初始化 |
尚未创建 |
deploy/ |
部署、迁移、回滚、烟测说明和配置示例 | 已创建 |
docs/ |
需求、架构、验收和测试文档 | 已存在 |
模板目录默认只读，不作为最终交付目录。
4. 初始化实际工程
后端已初始化。若在干净仓库中重新初始化，可参考：
Copy-Item -LiteralPath .\templates\server_sample -Destination .\server -Recurse
前端初始化：
Copy-Item -LiteralPath .\templates\front_sample\standard -Destination .\web -Recurse
初始化后需要检查：
| 检查项 | 要求 |
|---|---|
| 配置示例 | 只提交 etc/*.example.yaml、*.example.yaml 或 .env.example，不提交真实密码。 |
| 目录结构 | 后端延续 cmd/、internal/config/、internal/logic/、internal/models/、internal/routers/。 |
| 前端结构 | API 放入 src/api/，页面放入 src/views/，状态放入 Pinia。 |
| 模板引用 | 业务代码不直接写回 templates/。 |
5. 本地后端开发
常用命令：
Set-Location .\server
go mod tidy
go test ./...
go vet ./...
gofmt -w .
go run .\cmd\main\main.go
迁移命令按实际 CLI 保留：
Set-Location .\server
go run .\cmd\cli\main.go migrate
后端重新初始化后，应只提交 server/etc/*.example.yaml 或等价 .example 配置文件。本地真实配置应复制为 server/etc/ops_dev.yaml 等文件后再填写，并在 server/.gitignore 中排除。
后端本地配置要求：
| 配置 | 要求 |
|---|---|
| PostgreSQL | 本地可使用开发库；测试不能用 mock 数据库。 |
| SQLite 内存库 | 仅用于后端测试，验证真实 SQL 行为。 |
| 时序数据库 | 使用 TDengine 开源版；本地和验收环境均通过适配层配置连接信息，不在代码中写死地址或凭据。 |
| 通知渠道 | 本地使用测试账号或受控沙箱，不能提交真实凭据。 |
| traceId | 所有接口和任务日志必须可关联。 |
6. 本地前端开发
常用命令：
Set-Location .\web
pnpm install
pnpm dev
pnpm type:check
pnpm lint
pnpm build
前端联调要求：
| 项目 | 要求 |
|---|---|
| API 地址 | 通过本地配置读取，不写死到组件中。 |
| 状态覆盖 | 页面按 docs/首期UI状态覆盖.md 实现。 |
| mock 数据 | 只用于独立调试，验收必须连接真实后端 API。 |
| 文案 | 按模板 i18n 方式维护，不在组件中散落重复字符串。 |
7. Linux/麒麟验收部署检查项
部署说明放入 deploy/README.md。验收前必须确认：
| 检查项 | 要求 |
|---|---|
| 操作系统 | 明确 Linux 或麒麟版本、CPU 架构、补丁状态。 |
| 运行用户 | 后端、前端静态服务、数据库、时序库使用独立低权限账号。 |
| 网络策略 | 明确 Web 端口、API 端口、数据库端口、Trap/Syslog 接收端口和防火墙策略。 |
| 数据库 | PostgreSQL 版本、初始化库、备份路径、恢复演练方式。 |
| 时序库 | 选定产品版本、部署形态、保留策略、备份恢复方式。 |
| 配置 | 只使用现场配置文件，不把真实凭据提交进仓库。 |
| 日志 | 应用日志、审计日志、采集日志、通知日志有保存周期。 |
| 回滚 | 后端二进制、前端静态包、数据库迁移均有回滚方案。 |
| 烟测 | 登录、资源列表、告警列表、通知记录、工单流转、报表查询可验证。 |
8. 验收材料目录
验收证据/
01-首页总览/
02-资源监控/
03-H3C网络设备/
04-告警闭环/
05-通知记录/
06-工单闭环/
07-报表大屏/
08-权限审计/
09-3D机房接口/
10-部署与烟测/
证据目录不要求当前仓库立即创建。正式验收时应保存截图、录像、接口响应、日志和数据库查询结果。