ai_wht_wechat/go_backend/UBUNTU_SCRIPTS_GUIDE.md

# Ubuntu 启动脚本使用指南

## 📁 脚本文件列表

| 脚本文件 | 用途 | 推荐场景 |
|---------|------|----------|
| `restart.sh` | 智能重启脚本(支持 dev/prod) | **推荐使用** - 开发和生产环境通用 |
| `start_prod.sh` | 生产环境快速启动 | 仅生产环境快速部署 |
| `stop.sh` | 停止服务脚本 | 停止所有运行的服务 |
| `start.sh` | 开发环境启动(原有) | 开发环境直接运行 |

---

## 🚀 快速开始

### 1. 赋予执行权限
```bash
cd go_backend

# 一次性赋予所有脚本执行权限
chmod +x restart.sh start_prod.sh stop.sh start.sh
```

### 2. 启动开发环境
```bash
# 方式1: 使用 restart.sh (推荐)
./restart.sh dev

# 方式2: 默认启动开发环境
./restart.sh

# 方式3: 使用原有脚本
./start.sh
```

### 3. 启动生产环境
```bash
# 方式1: 使用 restart.sh (推荐)
./restart.sh prod

# 方式2: 使用专用脚本
./start_prod.sh
```

### 4. 停止服务
```bash
./stop.sh
```

---

## 📖 详细说明

### restart.sh - 智能重启脚本 ⭐推荐

**功能特点:**
- ✅ 自动停止旧服务
- ✅ 支持开发/生产环境切换
- ✅ 完整的环境检查
- ✅ 多重端口清理机制
- ✅ 启动验证和错误检测
- ✅ 彩色输出,易于阅读

**使用方法:**
```bash
# 启动开发环境 (端口 8080)
./restart.sh
./restart.sh dev

# 启动生产环境 (端口 8070)
./restart.sh prod

# 查看帮助
./restart.sh help
```

**输出示例:**
```
========================================
  AI小红书 Go 后端服务重启脚本
========================================
环境: dev
端口: 8080
日志: ai_xhs.log

=== [1/4] 停止现有服务 ===
✅ 端口 8080 已释放

=== [2/4] 环境检查 ===
✅ Go 环境: go version go1.21.0 linux/amd64
✅ 主文件: main.go
✅ 配置文件: config/config.dev.yaml

=== [3/4] 下载依赖 ===
✅ 依赖下载完成

=== [4/4] 启动服务 ===
✅ 服务已启动，进程 PID: 12345

========================================
  🎉 服务启动成功!
========================================

服务信息:
  环境:     dev
  端口:     8080
  进程PID:  12345
  日志文件: ai_xhs.log

快捷命令:
  查看日志:   tail -f ai_xhs.log
  停止服务:   kill -9 12345
  
访问地址:
  本地:       http://localhost:8080
```

---

### start_prod.sh - 生产环境快速启动

**功能特点:**
- ✅ 专为生产环境优化
- ✅ 简洁快速
- ✅ 固定端口 8070
- ✅ 独立日志文件 `ai_xhs_prod.log`

**使用方法:**
```bash
./start_prod.sh
```

---

### stop.sh - 停止服务脚本

**功能特点:**
- ✅ 同时停止开发和生产环境
- ✅ 多种停止方法确保彻底清理
- ✅ 自动验证停止结果
- ✅ 清理所有相关进程

**使用方法:**
```bash
./stop.sh
```

**清理范围:**
- 所有 `go run main.go` 进程
- 占用 8080 端口的进程(开发环境)
- 占用 8070 端口的进程(生产环境)
- 其他相关 main.go 进程

---

## 🔧 环境变量配置

### 通过环境变量覆盖配置

脚本支持通过环境变量覆盖配置文件:

```bash
# 设置环境
export APP_ENV=prod

# 覆盖数据库配置
export DB_HOST=prod-server.com
export DB_PASSWORD=secure_password

# 覆盖微信配置
export WECHAT_APP_ID=wx_prod_id
export WECHAT_APP_SECRET=wx_prod_secret

# 启动服务
./restart.sh
```

**支持的环境变量:** 详见 [ENV_CONFIG_GUIDE.md](ENV_CONFIG_GUIDE.md)

---

## 📋 日志管理

### 查看实时日志
```bash
# 开发环境
tail -f ai_xhs.log

# 生产环境
tail -f ai_xhs_prod.log

# 查看最后 50 行
tail -n 50 ai_xhs.log

# 搜索错误日志
grep -i "error\|fatal\|panic" ai_xhs.log
```

### 日志文件说明

| 文件 | 用途 | 环境 |
|------|------|------|
| `ai_xhs.log` | 开发环境日志 | dev |
| `ai_xhs_prod.log` | 生产环境日志 | prod |

---

## 🛠 常用命令

### 检查服务状态
```bash
# 查看 Go 进程
ps aux | grep "go run main.go"

# 查看端口占用
lsof -i:8080    # 开发环境
lsof -i:8070    # 生产环境

# 查看所有监听端口
netstat -tunlp | grep go
```

### 手动停止服务
```bash
# 方法1: 使用 PID (推荐)
kill -9 <PID>

# 方法2: 停止所有 go run 进程
pkill -f "go run main.go"

# 方法3: 通过端口停止
sudo fuser -k 8080/tcp
```

### 测试服务
```bash
# 测试服务是否启动
curl http://localhost:8080/api/health

# 查看返回内容
curl -i http://localhost:8080/api/health
```

---

## ⚠️ 注意事项

### 1. 权限问题
某些清理操作需要 sudo 权限:
```bash
# 如果遇到权限问题,使用 sudo
sudo ./stop.sh
```

### 2. 端口冲突
如果端口被其他程序占用:
```bash
# 查看占用端口的程序
lsof -i:8080

# 修改配置文件中的端口
vim config/config.dev.yaml
```

### 3. 日志文件过大
定期清理日志:
```bash
# 清空日志文件
> ai_xhs.log

# 或删除旧日志
rm ai_xhs.log
```

### 4. 后台运行说明
- 脚本使用 `nohup` 在后台运行服务
- 关闭终端不会停止服务
- 必须使用 `kill` 或 `stop.sh` 停止服务

---

## 🔄 系统服务化 (可选)

### 创建 systemd 服务

如果需要开机自启动,可以创建系统服务:

```bash
# 创建服务文件
sudo vim /etc/systemd/system/ai_xhs.service
```

添加内容:
```ini
[Unit]
Description=AI XHS Go Backend
After=network.target mysql.service

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/go_backend
Environment="APP_ENV=prod"
ExecStart=/usr/local/go/bin/go run main.go
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启用服务:
```bash
# 重载配置
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start ai_xhs

# 设置开机自启
sudo systemctl enable ai_xhs

# 查看状态
sudo systemctl status ai_xhs

# 查看日志
sudo journalctl -u ai_xhs -f
```

---

## 📞 故障排查

### 问题1: 服务启动失败
```bash
# 检查日志
tail -f ai_xhs.log

# 检查配置文件
cat config/config.dev.yaml

# 检查 Go 环境
go version
```

### 问题2: 端口无法释放
```bash
# 强制停止
sudo ./stop.sh

# 检查是否还有进程
lsof -i:8080

# 手动清理
sudo fuser -k 8080/tcp
```

### 问题3: 找不到依赖
```bash
# 重新下载依赖
go mod tidy
go mod download

# 清理缓存
go clean -modcache
```

---

## 📝 快速参考

### 一键部署生产环境
```bash
# 1. 进入目录
cd go_backend

# 2. 赋予权限
chmod +x restart.sh

# 3. 设置环境变量(可选)
export DB_PASSWORD=your_password

# 4. 启动服务
./restart.sh prod

# 5. 查看日志
tail -f ai_xhs.log
```

### 一键停止所有服务
```bash
chmod +x stop.sh
./stop.sh
```

---

## 🎯 最佳实践

1. **使用 restart.sh** - 功能最完善,错误检查最全面
2. **配置环境变量** - 敏感信息不要写入配置文件
3. **定期查看日志** - 及时发现问题
4. **使用 systemd** - 生产环境推荐系统服务化
5. **备份配置文件** - 修改前先备份

---

## 📚 相关文档

- [环境变量配置指南](ENV_CONFIG_GUIDE.md)
- [数据库迁移指南](DATABASE_MIGRATION_GUIDE.md)
- [微信登录集成指南](WECHAT_LOGIN_GUIDE.md)