first commit

go_backend/UBUNTU_SCRIPTS_GUIDE.md

@@ -0,0 +1,412 @@
+# 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)