# 风七六本地生活服务平台 - 开发环境管理

> **团队所有人随时看环境状态、部署记录、部署文件、服务健康度，工作完全对齐，不用再问人。**

---

## 📁 目录结构

```
devops-environment/
├── config/          # 环境配置文件
├── deploy/          # 部署脚本和日志
│   └── logs/        # 部署日志目录
├── docker-compose/  # 容器编排文件
├── docs/            # 部署流程、环境说明文档
├── scripts/         # 服务状态检查脚本
│   ├── check-status.ps1      # 服务状态检查脚本
│   ├── deploy-service.ps1    # 统一部署脚本
│   └── status-dashboard.html # 状态展示网页
└── README.md        # 环境使用文档（本文件）
```

---

## 🌐 环境状态看板

### 在线查看（推荐）

- **访问地址**: http://localhost:8080/status
- **自动刷新**: 每30秒自动更新
- **展示内容**:
  - 容器运行状态
  - Nacos注册状态
  - 服务健康状态
  - 最近部署记录

### 本地脚本检查

```powershell
# 检查所有服务状态
.\scripts\check-status.ps1

# 检查单个服务
.\scripts\check-status.ps1 -service auth-service

# 生成HTML报告
.\scripts\check-status.ps1 -outputHtml -htmlPath "status.html"
```

---

## 🚀 统一部署

### 部署单个服务

```powershell
# 部署指定服务
.\scripts\deploy-service.ps1 -service user-service -version v1.1.0

# 强制拉取最新镜像
.\scripts\deploy-service.ps1 -service auth-service -version v1.1.0 -forcePull
```

### 部署多个服务

```powershell
.\scripts\deploy-service.ps1 -service @("user-service", "auth-service", "order-service") -version v1.1.0
```

### 部署所有服务

```powershell
.\scripts\deploy-service.ps1 -allServices -version v1.1.0
```

### 部署日志

部署日志自动记录到 `deploy/logs/deploy-YYYY-MM-DD.log`

---

## 📋 服务列表

| 服务名称              | 端口   | 容器名称                        | 状态 |
|-------------------|------|-----------------------------|----|
| api-gateway       | 8080 | fzx-aliyun-apigateway       | ✅  |
| user-service      | 8091 | fzx-aliyun-userservice      | ✅  |
| merchant-service  | 8085 | fzx-aliyun-merchantservice  | ✅  |
| order-service     | 8086 | fzx-aliyun-orderservice     | ✅  |
| product-service   | 8087 | fzx-aliyun-productservice   | ✅  |
| rider-service     | 8088 | fzx-aliyun-riderservice     | ✅  |
| map-service       | 8089 | fzx-aliyun-mapservice       | ✅  |
| auth-service      | 8096 | fzx-aliyun-auth             | ✅  |
| marketing-service | 8090 | fzx-aliyun-marketingservice | ✅  |
| upload-service    | 8092 | fzx-aliyun-uploadservice    | ✅  |

### 基础设施服务

| 服务名称     | 端口   | 状态 |
|----------|------|----|
| mariadb  | 3306 | ✅  |
| redis    | 6379 | ✅  |
| nacos    | 8848 | ✅  |
| registry | 5000 | ✅  |

---

## 🔧 常用命令

### 容器管理

```powershell
# 查看所有容器状态
podman ps

# 查看容器日志
podman logs fzx-aliyun-auth

# 进入容器
podman exec -it fzx-aliyun-auth bash

# 停止容器
podman stop fzx-aliyun-auth

# 删除容器
podman rm fzx-aliyun-auth
```

### Nacos管理

```powershell
# 查看注册的服务列表
curl http://localhost:8848/nacos/v1/ns/service/list

# 查看服务实例
curl http://localhost:8848/nacos/v1/ns/instance/list?serviceName=auth-service

# 注销服务实例
curl -X DELETE "http://localhost:8848/nacos/v1/ns/instance?serviceName=auth-service&ip=10.89.5.68&port=8096"
```

### 版本管理

```powershell
# 查看当前版本
Get-Content VERSION

# 自动计算新版本
$VERSION = & .\scripts\auto-version.ps1
Write-Host "新版本: v$VERSION"
```

---

## 🐛 常见问题自愈

### 问题1: 服务未注册到Nacos

**现象**: Nacos服务列表中看不到服务

**排查步骤**:

1. 检查容器是否启动: `podman ps | Select-String auth`
2. 检查容器日志: `podman logs fzx-aliyun-auth`
3. 检查Nacos连接配置: 确认环境变量 `NACOS_SERVER_ADDR=nacos:8848`
4. 检查服务是否启用发现: 确认 `NACOS_DISCOVERY_ENABLED=true`

**解决方案**:

```powershell
# 重启服务
.\scripts\deploy-service.ps1 -service auth-service -version v1.1.0
```

### 问题2: 数据库连接失败

**现象**: 容器日志显示 "Access denied" 或 "UnknownHost"

**排查步骤**:

1. 检查数据库容器状态: `podman ps | Select-String mariadb`
2. 验证数据库连接:
   ```powershell
   podman exec fzx-aliyun-mariadb mysql -u fzx_app -pfzx_app_password_2024 -e "SELECT 1"
   ```
3. 检查环境变量配置

**解决方案**:

```powershell
# 重置数据库密码
podman exec fzx-aliyun-mariadb mysql -u root -pfzx_root_password_2024 -e "ALTER USER 'fzx_app'@'%' IDENTIFIED BY 'fzx_app_password_2024'"
```

### 问题3: 端口冲突

**现象**: 容器启动失败，显示 "port already in use"

**解决方案**:

```powershell
# 查找占用端口的进程
netstat -ano | Select-String ":8082"

# 杀死进程（替换PID）
taskkill /F /PID 12345
```

### 问题4: 服务启动超时

**现象**: 服务启动时间过长或超时

**排查步骤**:

1. 检查数据库连接
2. 检查Nacos连接
3. 检查网络连通性

**解决方案**:

```powershell
# 增加超时时间
.\scripts\deploy-service.ps1 -service auth-service -version v1.1.0 -timeout 180
```

---

## 📝 部署记录

| 时间               | 部署人   | 服务           | 版本     | 状态   |
|------------------|-------|--------------|--------|------|
| 2026-05-29 14:00 | admin | auth-service | v1.1.0 | ✅ 成功 |
| 2026-05-29 13:30 | admin | user-service | v1.1.0 | ✅ 成功 |

---

## 👥 团队协作规范

### 部署流程

1. **代码提交**: 代码合并到 `develop` 分支
2. **版本更新**: 运行 `auto-version.ps1` 自动计算版本
3. **构建镜像**: CI/CD自动构建并推送镜像到 registry
4. **部署验证**: 使用统一部署脚本部署并验证

### 注意事项

- ✅ 禁止直接在生产环境手动修改配置
- ✅ 所有配置变更必须通过配置中心（Nacos）
- ✅ 部署前必须确认版本号正确
- ✅ 部署后必须验证服务注册状态

---

## 📞 联系方式

| 角色        | 姓名 | 联系方式                |
|-----------|----|---------------------|
| 技术负责人     | 张工 | zhang@fengqiliu.com |
| DevOps负责人 | 李工 | li@fengqiliu.com    |
| 运维支持      | 王工 | wang@fengqiliu.com  |

---

**文档版本**: v1.0
**最后更新**: 2026-05-29
**适用环境**: 开发环境（aliyun-dev）