138 lines
4.9 KiB
Markdown
138 lines
4.9 KiB
Markdown
# 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. 初始化实际工程
|
||
|
||
后端已初始化。若在干净仓库中重新初始化，可参考：
|
||
|
||
```powershell
|
||
Copy-Item -LiteralPath .\templates\server_sample -Destination .\server -Recurse
|
||
```
|
||
|
||
前端初始化：
|
||
|
||
```powershell
|
||
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. 本地后端开发
|
||
|
||
常用命令：
|
||
|
||
```powershell
|
||
Set-Location .\server
|
||
go mod tidy
|
||
go test ./...
|
||
go vet ./...
|
||
gofmt -w .
|
||
go run .\cmd\main\main.go
|
||
```
|
||
|
||
迁移命令按实际 CLI 保留：
|
||
|
||
```powershell
|
||
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. 本地前端开发
|
||
|
||
常用命令：
|
||
|
||
```powershell
|
||
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. 验收材料目录
|
||
|
||
```text
|
||
验收证据/
|
||
01-首页总览/
|
||
02-资源监控/
|
||
03-H3C网络设备/
|
||
04-告警闭环/
|
||
05-通知记录/
|
||
06-工单闭环/
|
||
07-报表大屏/
|
||
08-权限审计/
|
||
09-3D机房接口/
|
||
10-部署与烟测/
|
||
```
|
||
|
||
证据目录不要求当前仓库立即创建。正式验收时应保存截图、录像、接口响应、日志和数据库查询结果。
|