# 运营后台 · 本地启动指南

> 这套后台 = 两个服务:**后端**(FastAPI,端口 8771)+ **前端**(Next.js,端口 3001)。
> 数据库是本机 **PostgreSQL**(端口 5432)。
> 访问地址:**http://localhost:3001** 账号 **admin** / 密码 **admin12345**

---

## 开机后通常不用管的

- **PG 开机自启**:本机 PostgreSQL 是 Homebrew `postgresql@16` 装的(`brew services` + LaunchAgent),登录系统时自动起,一般不用手动启。
- **表 / 账号 / 依赖都是持久的**:不用重新建表、建账号、`npm install`。

所以**重启电脑后,只需起 后端 + 前端 两个服务**(下面方式一或方式二二选一)。

---

## 方式一:前台启动(开发推荐,能看实时日志,Ctrl+C 停)

开两个终端窗口。

**终端 1 — 后端**
```bash
cd ~/Desktop/codes/shaguabijia-app-server
conda activate price
uvicorn app.admin.main:admin_app --port 8771 --reload
```

**终端 2 — 前端**
```bash
cd ~/Desktop/codes/shaguabijia-admin-web
npm run dev
```

然后浏览器开 **http://localhost:3001**。停止:各终端按 `Ctrl+C`。

> `--reload`:改后端代码自动重启(省得手动重起)。前端 `npm run dev` 自带热重载。

---

## 方式二:后台启动(一条命令拉起,日志落 /tmp)

```bash
cd ~/Desktop/codes/shaguabijia-admin-web
./start.sh        # 确保 PG + 起后端(8771) + 起前端(3001),全后台
./stop.sh         # 停掉后端 + 前端(PG 不动,它给别的也可能用)
```

看日志:
```bash
tail -f /tmp/admin-api.log     # 后端
tail -f /tmp/admin-web.log     # 前端
```

> 第一次用脚本前若提示无权限:`chmod +x start.sh stop.sh`(已预先加过执行权限,正常不用再加)。

---

## 访问

- 地址:**http://localhost:3001**
- 账号:**admin** / 密码:**admin12345**
- 前端第一次点进某个页面会**现编译、慢几秒**,之后就快。

---

## 仅这些情况才需要(平时不用)

```bash
# ① 新电脑 / 删过 node_modules → 装前端依赖
cd ~/Desktop/codes/shaguabijia-admin-web && npm install

# ② 全新数据库、没建过 admin 表 → 建表
cd ~/Desktop/codes/shaguabijia-app-server && conda activate price && alembic upgrade head

# ③ 没有管理员账号 → 建一个超管(密码可自改)
cd ~/Desktop/codes/shaguabijia-app-server && conda activate price && \
  python scripts/create_admin.py --username admin --password 'admin12345' --role super_admin
```

---

## 排障

| 现象 | 原因 / 解决 |
|---|---|
| 后端报数据库连接失败 | PG 没起 → `brew services start postgresql@16` |
| 端口被占(8771/3001 起不来) | `./stop.sh`,或 `lsof -ti:8771 \| xargs kill`(3001 同理),再重起 |
| 登录转圈 / 失败,控制台 CORS 报错 | 前端端口必须在后端 CORS 白名单(`app/admin/main.py` 的 `_dev_origins`)。前端默认 3001,已配好;若你改了前端端口,记得同步这里并重启后端 |
| 改了后端代码不生效 | 用 `--reload`(方式一已带、脚本已带);否则手动重起后端 |
| 控制台 antd 波纹 React 版本警告 | 已禁用 wave,不再出现;纯 dev 噪音、不影响功能 |

---

## 部署到线上?

本文档只讲本地。生产部署(systemd + pm2 + nginx + 域名 admin.shaguabijia.com)见 [../README.md](../README.md)。