ln0422
501f8985ec
- Add BASE_PATH config, include all routers with prefix
- Inject {{ base }} Jinja2 global for all template URLs
- Add window.BASE_PATH for static JS files
- Update Nginx to proxy /careerbot/ path
- Add OPS_MANUAL.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
397 lines
11 KiB
Markdown
397 lines
11 KiB
Markdown
# CareerBot 线上运维手册
|
||
|
||
## 1. 服务器信息
|
||
|
||
| 项目 | 详情 |
|
||
|------|------|
|
||
| 云服务商 | 阿里云 ECS |
|
||
| 公网 IP | `39.106.14.107` |
|
||
| 操作系统 | Alibaba Cloud Linux 3 (OpenAnolis Edition) |
|
||
| 配置 | 2 核 CPU / 2GB 内存 / 40GB 磁盘 |
|
||
| Python 版本 | 3.11.13 |
|
||
| Nginx 版本 | 1.20.1 |
|
||
| Gitea 版本 | 1.22.6 |
|
||
|
||
---
|
||
|
||
## 2. 账号信息
|
||
|
||
### 2.1 服务器账号
|
||
|
||
| 账号 | 用途 | 登录方式 |
|
||
|------|------|---------|
|
||
| `root` | 系统管理 | SSH 密钥 (`~/.ssh/id_ed25519`) |
|
||
| `deploy` | 应用部署和运行 | SSH 密钥（同上），sudo 免密 |
|
||
| `gitea` | Gitea 服务运行 | 系统用户，不可直接登录 |
|
||
| `nginx` | Nginx 服务运行 | 系统用户，不可直接登录 |
|
||
|
||
**本地 SSH 快捷连接**（已配置在 `~/.ssh/config`）：
|
||
```bash
|
||
ssh ecs # 以 deploy 用户连接
|
||
ssh root@ecs # 以 root 用户连接（需将 config 中 User 临时改为 root，或直接用 IP）
|
||
ssh root@39.106.14.107 # root 直连
|
||
```
|
||
|
||
### 2.2 应用账号
|
||
|
||
| 系统 | 地址 | 账号 | 密码 |
|
||
|------|------|------|------|
|
||
| CareerBot 管理后台 | `http://39.106.14.107/admin/login` | `ln0422@gmail.com` | `qshs123456` |
|
||
| Gitea 代码管理 | `http://39.106.14.107:3000` | `ln0422` | `Qshs123456_` |
|
||
|
||
### 2.3 ECS 用户密码
|
||
|
||
| 用户 | 密码 |
|
||
|------|------|
|
||
| `deploy` | `CareerBot2026!` |
|
||
|
||
> **注意**：日常运维通过 SSH 密钥登录，密码仅在密钥不可用时作为备用。
|
||
|
||
---
|
||
|
||
## 3. 服务架构
|
||
|
||
```
|
||
外部访问
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────┐
|
||
│ Nginx (:80) │
|
||
│ 配置: /etc/nginx/sites-enabled/ │
|
||
│ 日志: /var/log/nginx/ │
|
||
├─────────────────────────────────────────┤
|
||
│ http://39.106.14.107/ │
|
||
│ → proxy_pass http://127.0.0.1:8000 │
|
||
│ → CareerBot (uvicorn) │
|
||
├─────────────────────────────────────────┤
|
||
│ http://39.106.14.107:3000 │
|
||
│ → Gitea (直接监听，未经 Nginx 代理) │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 端口使用
|
||
|
||
| 端口 | 服务 | 监听地址 | 防火墙 | 安全组 |
|
||
|------|------|---------|--------|--------|
|
||
| 22 | SSH | 0.0.0.0 | 已放行 | 已放行 |
|
||
| 80 | Nginx → CareerBot | 0.0.0.0 | 已放行 | 已放行 |
|
||
| 443 | HTTPS (预留) | - | 已放行 | 已放行 |
|
||
| 3000 | Gitea | 0.0.0.0 | 已放行 | 已放行 |
|
||
| 8000 | CareerBot (uvicorn) | 127.0.0.1 | 内部 | 无需 |
|
||
|
||
---
|
||
|
||
## 4. 文件目录结构
|
||
|
||
```
|
||
/home/deploy/apps/CareerBot/ ← 项目根目录
|
||
├── venv/ ← Python 虚拟环境
|
||
├── app/ ← 应用代码
|
||
├── templates/ ← 页面模板
|
||
├── careerbot.db ← SQLite 数据库（重要数据！）
|
||
├── uploads/ ← 用户上传文件
|
||
├── requirements.txt
|
||
├── init_data.py
|
||
├── start.bat / stop.bat ← Windows 本地启动脚本（线上不用）
|
||
├── DESIGN.md ← 设计文档
|
||
└── OPS_MANUAL.md ← 本文档
|
||
|
||
/etc/systemd/system/
|
||
├── careerbot.service ← CareerBot systemd 服务
|
||
└── gitea.service ← Gitea systemd 服务
|
||
|
||
/etc/nginx/
|
||
├── nginx.conf ← Nginx 主配置
|
||
├── sites-available/
|
||
│ └── careerbot.conf ← CareerBot 站点配置
|
||
└── sites-enabled/
|
||
└── careerbot.conf → ../sites-available/careerbot.conf
|
||
|
||
/usr/local/bin/gitea ← Gitea 二进制文件
|
||
/etc/gitea/app.ini ← Gitea 配置文件
|
||
/var/lib/gitea/ ← Gitea 数据目录（仓库、数据库）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 常用运维命令
|
||
|
||
### 5.1 服务管理
|
||
|
||
```bash
|
||
# ── CareerBot ──
|
||
sudo systemctl status careerbot # 查看状态
|
||
sudo systemctl restart careerbot # 重启
|
||
sudo systemctl stop careerbot # 停止
|
||
sudo systemctl start careerbot # 启动
|
||
sudo journalctl -u careerbot -f # 实时查看日志
|
||
sudo journalctl -u careerbot --since "1 hour ago" # 查看最近1小时日志
|
||
|
||
# ── Nginx ──
|
||
sudo systemctl status nginx
|
||
sudo systemctl reload nginx # 重载配置（不中断连接）
|
||
sudo systemctl restart nginx # 重启
|
||
sudo nginx -t # 测试配置文件语法
|
||
|
||
# ── Gitea ──
|
||
sudo systemctl status gitea
|
||
sudo systemctl restart gitea
|
||
sudo journalctl -u gitea -f
|
||
```
|
||
|
||
### 5.2 代码更新部署
|
||
|
||
**从本地推送代码并部署到线上（标准流程）：**
|
||
|
||
```bash
|
||
# 1. 本地：提交并推送到 Gitea
|
||
cd D:/Files/Projects/VibeCoding/CareerBot
|
||
git add .
|
||
git commit -m "描述改动"
|
||
git push origin main
|
||
|
||
# 2. 线上：拉取并重启
|
||
ssh ecs "cd ~/apps/CareerBot && git pull && sudo systemctl restart careerbot"
|
||
```
|
||
|
||
**一键部署脚本（在本地执行）：**
|
||
```bash
|
||
ssh ecs "cd ~/apps/CareerBot && git pull origin main && sudo systemctl restart careerbot && sleep 2 && sudo systemctl is-active careerbot"
|
||
```
|
||
|
||
### 5.3 数据库操作
|
||
|
||
```bash
|
||
# 连接到 SQLite 数据库
|
||
ssh ecs "cd ~/apps/CareerBot && sqlite3 careerbot.db"
|
||
|
||
# 常用 SQL
|
||
.tables # 查看所有表
|
||
SELECT * FROM admin_user; # 查看管理员
|
||
SELECT token, note, max_questions, used_questions, is_active FROM access_token; # 查看令牌
|
||
SELECT * FROM recruiter_message ORDER BY created_at DESC LIMIT 10; # 最近招聘消息
|
||
SELECT COUNT(*) FROM chat_history; # 对话记录总数
|
||
.quit # 退出
|
||
```
|
||
|
||
### 5.4 系统监控
|
||
|
||
```bash
|
||
# 查看内存使用
|
||
ssh ecs "free -h"
|
||
|
||
# 查看磁盘使用
|
||
ssh ecs "df -h /"
|
||
|
||
# 查看各服务内存占用
|
||
ssh ecs "ps aux --sort=-rss | head -10"
|
||
|
||
# 查看端口监听
|
||
ssh ecs "ss -tlnp"
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 配置文件详情
|
||
|
||
### 6.1 CareerBot systemd 服务
|
||
|
||
文件：`/etc/systemd/system/careerbot.service`
|
||
```ini
|
||
[Unit]
|
||
Description=CareerBot Web Application
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=deploy
|
||
WorkingDirectory=/home/deploy/apps/CareerBot
|
||
ExecStart=/home/deploy/apps/CareerBot/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||
Restart=always
|
||
RestartSec=5
|
||
Environment=PATH=/home/deploy/apps/CareerBot/venv/bin:/usr/bin
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
关键参数：
|
||
- `--host 127.0.0.1`：只监听本地，由 Nginx 代理外部访问
|
||
- `Restart=always`：崩溃后自动重启
|
||
- `RestartSec=5`：重启间隔 5 秒
|
||
|
||
### 6.2 Nginx 站点配置
|
||
|
||
文件：`/etc/nginx/sites-available/careerbot.conf`
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name 39.106.14.107;
|
||
|
||
client_max_body_size 10M;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:8000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
# SSE 流式响应支持（关键！关闭缓冲）
|
||
proxy_buffering off;
|
||
proxy_cache off;
|
||
proxy_read_timeout 300s;
|
||
}
|
||
|
||
location /uploads/ {
|
||
alias /home/deploy/apps/CareerBot/uploads/;
|
||
}
|
||
}
|
||
```
|
||
|
||
关键配置说明：
|
||
- `proxy_buffering off` + `proxy_cache off`：**必须关闭**，否则 SSE 流式对话无法实时返回
|
||
- `proxy_read_timeout 300s`：LLM 长回复可能需要较长时间
|
||
- `client_max_body_size 10M`：允许上传最大 10MB 文件
|
||
|
||
### 6.3 防火墙规则
|
||
|
||
```bash
|
||
# 查看当前规则
|
||
sudo firewall-cmd --list-ports
|
||
# 输出: 22/tcp 80/tcp 443/tcp 3000/tcp
|
||
|
||
# 添加新端口（如未来部署新项目）
|
||
sudo firewall-cmd --permanent --add-port=PORT/tcp
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
> **注意**：开放端口还需要在阿里云控制台的**安全组**中同步添加入方向规则，否则外部仍无法访问。
|
||
|
||
---
|
||
|
||
## 7. 备份策略
|
||
|
||
### 7.1 数据库备份
|
||
|
||
CareerBot 的所有业务数据存储在 SQLite 文件中：
|
||
|
||
```bash
|
||
# 手动备份
|
||
ssh ecs "cp ~/apps/CareerBot/careerbot.db ~/apps/CareerBot/careerbot.db.bak.$(date +%Y%m%d)"
|
||
|
||
# 下载到本地
|
||
scp ecs:~/apps/CareerBot/careerbot.db ./careerbot_backup_$(date +%Y%m%d).db
|
||
```
|
||
|
||
### 7.2 Gitea 数据备份
|
||
|
||
```bash
|
||
# Gitea 数据和仓库
|
||
ssh ecs "sudo tar czf /tmp/gitea-backup.tar.gz /var/lib/gitea /etc/gitea"
|
||
scp ecs:/tmp/gitea-backup.tar.gz ./gitea-backup.tar.gz
|
||
```
|
||
|
||
### 7.3 需要备份的关键文件
|
||
|
||
| 文件/目录 | 说明 | 重要程度 |
|
||
|-----------|------|---------|
|
||
| `~/apps/CareerBot/careerbot.db` | CareerBot 全部业务数据 | **极高** |
|
||
| `~/apps/CareerBot/uploads/` | 用户上传的文件 | 高 |
|
||
| `/var/lib/gitea/` | Gitea 所有仓库和数据 | **极高** |
|
||
| `/etc/gitea/app.ini` | Gitea 配置 | 中 |
|
||
| `/etc/nginx/sites-available/` | Nginx 站点配置 | 中 |
|
||
| `/etc/systemd/system/careerbot.service` | 服务配置 | 低（可重建） |
|
||
|
||
---
|
||
|
||
## 8. 故障排查
|
||
|
||
### 8.1 CareerBot 无法访问
|
||
|
||
```bash
|
||
# 1. 检查服务状态
|
||
sudo systemctl status careerbot
|
||
|
||
# 2. 查看错误日志
|
||
sudo journalctl -u careerbot --since "10 min ago"
|
||
|
||
# 3. 检查端口
|
||
ss -tlnp | grep 8000
|
||
|
||
# 4. 检查 Nginx
|
||
sudo nginx -t
|
||
sudo systemctl status nginx
|
||
|
||
# 5. 手动启动测试
|
||
cd ~/apps/CareerBot
|
||
source venv/bin/activate
|
||
uvicorn app.main:app --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
### 8.2 AI 对话不工作
|
||
|
||
- 检查管理后台 LLM Config 是否已配置（API URL、API Key、Model Name）
|
||
- 点击 "Test Connection" 测试连通性
|
||
- 确认 ECS 能访问外网：`curl https://api.deepseek.com`
|
||
|
||
### 8.3 Gitea 无法访问
|
||
|
||
```bash
|
||
sudo systemctl status gitea
|
||
sudo journalctl -u gitea --since "10 min ago"
|
||
# 检查 3000 端口和安全组
|
||
```
|
||
|
||
### 8.4 磁盘/内存不足
|
||
|
||
```bash
|
||
# 查看磁盘
|
||
df -h /
|
||
|
||
# 清理日志
|
||
sudo journalctl --vacuum-time=7d
|
||
|
||
# 查看内存
|
||
free -h
|
||
|
||
# 查看占用最多的进程
|
||
ps aux --sort=-rss | head -10
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 新项目部署指南
|
||
|
||
后续在同一台 ECS 上部署新项目的标准流程：
|
||
|
||
1. **Gitea 上创建仓库**：`http://39.106.14.107:3000` → New Repository
|
||
|
||
2. **本地推送代码**
|
||
3. **ECS 上克隆并配置**：
|
||
```bash
|
||
cd ~/apps
|
||
git clone http://39.106.14.107:3000/ln0422/新项目.git
|
||
# 安装依赖、初始化等
|
||
```
|
||
|
||
4. **创建 systemd 服务**（参考 careerbot.service，注意更换端口号）
|
||
|
||
5. **添加 Nginx 站点配置**：
|
||
```bash
|
||
sudo vim /etc/nginx/sites-available/新项目.conf
|
||
sudo ln -s /etc/nginx/sites-available/新项目.conf /etc/nginx/sites-enabled/
|
||
sudo nginx -t && sudo systemctl reload nginx
|
||
```
|
||
|
||
6. **如需新端口**：防火墙 + 阿里云安全组同步放行
|
||
|
||
---
|
||
|
||
## 10. 安全注意事项
|
||
|
||
1. **SSH 密钥**：本地私钥 `~/.ssh/id_ed25519` 请妥善保管，丢失需重新生成并更新服务器
|
||
2. **Gitea 端口**：3000 端口对外开放，建议设置强密码，或后续通过 Nginx 代理并限制访问
|
||
3. **数据库文件**：`careerbot.db` 不应对外暴露，uvicorn 仅监听 127.0.0.1 已确保安全
|
||
4. **定期更新**：定期执行 `sudo dnf update -y` 更新系统安全补丁
|
||
5. **HTTPS**：后续绑定域名后建议配置 Let's Encrypt SSL 证书
|