# 智途投送后端操作手册

> 服务器：阿里云 ECS `121.41.216.243`（Ubuntu 24.04）
> 部署路径：`/opt/zhitu/`
> 服务名：`zhitu.service`
> 数据库：SQLite `/opt/zhitu/zhitu.db`

---

## 1. 连接服务器

```bash
ssh root@121.41.216.243
# 输入密码
```

---

## 2. 服务启停（最常用）

| 操作 | 命令 |
|------|------|
| 查看状态 | `systemctl status zhitu` |
| 启动服务 | `systemctl start zhitu` |
| 停止服务 | `systemctl stop zhitu` |
| 重启服务 | `systemctl restart zhitu` |
| 重载配置 | `systemctl daemon-reload` |
| 开机自启 | `systemctl enable zhitu`（已配置）|

---

## 3. 查看日志（排错必备）

```bash
# 查看最新 50 行日志
journalctl -u zhitu -n 50

# 实时跟踪日志（调试时用，按 Ctrl+C 退出）
journalctl -u zhitu -f
```

---

## 4. 改 Worker 数量为 1（避免 SQLite 并发锁）

当前配置为 2 个 worker，SQLite 并发写入时可能锁竞争导致请求卡住，建议改为 1 个：

```bash
sed -i 's/-w 2/-w 1/' /etc/systemd/system/zhitu.service
systemctl daemon-reload
systemctl restart zhitu
systemctl status zhitu
```

---

## 5. 备份数据库

数据库文件在 `/opt/zhitu/zhitu.db`，课程结束前务必备份：

```bash
# 方式一：在服务器上备份到 root 目录
cp /opt/zhitu/zhitu.db ~/zhitu_backup_$(date +%Y%m%d_%H%M%S).db

# 方式二：下载到本地电脑（在本地终端执行）
scp root@121.41.216.243:/opt/zhitu/zhitu.db D:\zhitu_backup.db
```

---

## 6. 修改后端代码后热更新

改完 `app.py` 后需要重启生效：

```bash
# 先检查语法
python3 -m py_compile /opt/zhitu/app.py

# 语法通过后重启
systemctl restart zhitu
```

---

## 7. 常用验证命令

```bash
# 测试后端是否存活
curl http://121.41.216.243/api/ping

# 查看所有需求（无需登录）
curl http://121.41.216.243/api/demands

# 查看账号列表（无需登录）
curl http://121.41.216.243/api/auth/accounts

# 直接查看数据库中的 token（调试用）
sqlite3 /opt/zhitu/zhitu.db "SELECT * FROM tokens;"

# 查看所有需求记录
sqlite3 /opt/zhitu/zhitu.db "SELECT * FROM demands;"
```

---

## 8. 网络/端口检查

```bash
# 查看 5000 端口是否在监听
ss -tlnp | grep 5000

# 查看 Nginx 状态
systemctl status nginx

# 查看防火墙状态
ufw status
```

---

## 9. 常见问题速查

| 现象 | 可能原因 | 解决 |
|------|----------|------|
| APP 上报 500 | `_demand_id_counter` 内存计数器归零导致主键冲突 | 已修复：改为数据库查询生成 ID |
| APP 上报超时/卡住 | Gunicorn 多 worker + SQLite 并发锁竞争 | 改 `-w 1` |
| APP 登录 401 | Token 跨 worker 不共享 / localStorage 缓存旧地址 | 已修复：Token 存数据库；检查 APP 服务器地址设置 |
| 电脑端首页 404 | 前端静态文件未上传到 `/opt/zhitu/` | 确保 `index.html`、`css/`、`js/` 都在部署目录 |
| 服务启动失败 | 语法错误 / 端口被占 | `python3 -m py_compile /opt/zhitu/app.py` 检查语法 |

---

## 10. 关键文件路径

| 文件/目录 | 路径 |
|-----------|------|
| 后端主程序 | `/opt/zhitu/app.py` |
| 数据库 | `/opt/zhitu/zhitu.db` |
| 服务配置 | `/etc/systemd/system/zhitu.service` |
| Nginx 配置 | `/etc/nginx/sites-enabled/zhitu` |
| Python 虚拟环境 | `/opt/zhitu/venv/` |
| 日志输出 | `journalctl -u zhitu` |

---

*手册生成时间：2026-05-23*
