# 部署到服务器 · 干净安装

这份说明对应「只拷代码，不带 data 目录」的方式 —— 服务器上是一个全新的空白系统。

---

## 一、服务器要求

| 项 | 要求 |
|---|---|
| 系统 | Linux（Ubuntu / CentOS / Debian 都行），macOS 也可以 |
| Python | **3.7 或更高**，只用标准库，不需要 pip install 任何包 |
| 内存 | 512MB 够用 |
| 磁盘 | 200MB（代码 1.3MB + 后续数据增长） |

检查 Python：

```bash
python3 --version
```

没有的话：

```bash
# Ubuntu / Debian
sudo apt update && sudo apt install -y python3
# CentOS / RHEL
sudo yum install -y python3
```

---

## 二、上传并解压

在**本机**执行（把 IP 和用户名换成你的）：

```bash
scp store-ops-server.zip root@你的服务器IP:/opt/
```

在**服务器**执行：

```bash
cd /opt
unzip store-ops-server.zip
cd store-ops
chmod +x start.sh
```

解压后的目录结构：

```
store-ops/
├── backend/          后端（Python，零依赖）
├── frontend/         前端（含本地 ECharts）
├── sync/             生意经同步脚本（服务器上通常用不到，见第六节）
├── tools/            规则文档导出工具
├── deploy/           systemd 服务模板
├── start.sh          启动脚本
├── DEPLOY.md         本说明
└── README.md         功能说明
```

---

## 三、试跑一下

```bash
cd /opt/store-ops
./start.sh
```

第一次启动会看到：

```
 [首次启动] 已创建管理员账号 admin / admin123 —— 登录后请立刻修改密码
==============================================================
 门店检测工作台已启动
 本机访问: http://127.0.0.1:8787
 局域网:   http://1.2.3.4:8787
 ...
```

浏览器打开 `http://服务器IP:8787`：

1. 用 **admin / admin123** 登录
2. 会强制要求改密码
3. 进去后是「还没有数据」的引导页

`Ctrl + C` 停止。

---

## 四、让它常驻后台（systemd）

```bash
# 1. 建一个专用用户（不建议用 root 跑）
sudo useradd -r -s /sbin/nologin storeops

# 2. 改目录归属
sudo chown -R storeops:storeops /opt/store-ops

# 3. 装服务
sudo cp /opt/store-ops/deploy/store-ops.service /etc/systemd/system/
sudo vim /etc/systemd/system/store-ops.service   # 确认 WorkingDirectory 路径对不对

# 4. 启动
sudo systemctl daemon-reload
sudo systemctl enable --now store-ops

# 5. 看状态和日志
sudo systemctl status store-ops
sudo journalctl -u store-ops -f
```

重启服务器后会自动起来。

---

## 五、放行端口

服务器通常有云厂商的**安全组**，光开系统防火墙不够。

```bash
# 系统防火墙（Ubuntu）
sudo ufw allow 8787/tcp

# CentOS
sudo firewall-cmd --permanent --add-port=8787/tcp && sudo firewall-cmd --reload
```

然后到云控制台 → 安全组 → 入方向 → 添加 8787 端口。

> 如果想用 80 端口，把 `PORT=80` 写进 service 文件，或者前面挂一个 nginx 反代。

### 关于 HTTPS —— 映射到域名（必读）

要让别人用 `https://yhm-shop-data.hzbeautybox.com/` 访问，需要四步，缺一不可：

**第 1 步：DNS 加一条 A 记录**

找管 `hzbeautybox.com` 域名的人（IT / 运维）加：

| 类型 | 主机记录 | 记录值 | TTL |
|---|---|---|---|
| A | `yhm-shop-data` | 服务器的**公网 IP** | 600 |

验证生效：

```bash
dig +short yhm-shop-data.hzbeautybox.com    # 应该返回你的服务器 IP
```

> 如果服务器在内网、没有公网 IP，这条 A 记录要指向内网 DNS 能解析的地址，
> 或者用内网 DNS 服务器单独加一条记录。

**第 2 步：应用改成只监听本机**

```bash
# 改 systemd 的 ExecStart，加上 --local
ExecStart=/bin/bash /opt/store-ops/start.sh --local
sudo systemctl daemon-reload && sudo systemctl restart store-ops
```

这样 8787 端口不对公网开放，只能被 nginx 访问。

**第 3 步：装 nginx 并反代**

```bash
sudo apt install -y nginx
sudo cp /opt/store-ops/deploy/nginx-yhm-shop-data.conf /etc/nginx/conf.d/
```

**第 4 步：配证书（二选一）**

```bash
# A. 免费证书（推荐，需公网能访问 80 端口）
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yhm-shop-data.hzbeautybox.com

# B. 公司已有证书：把 .crt / .key 放到 /etc/nginx/ssl/，文件名对上即可
```

然后：

```bash
sudo nginx -t && sudo systemctl reload nginx
```

浏览器打开 `https://yhm-shop-data.hzbeautybox.com/` 应该能看到登录页。

> 应用检测到 `X-Forwarded-Proto: https` 时会自动给会话 Cookie 加 `Secure` 标记。

**安全组 / 防火墙要放行 80 和 443**（8787 不用对外了）：

```bash
sudo ufw allow 80/tcp && sudo ufw allow 443/tcp && sudo ufw delete allow 8787/tcp
```

---

## 六、关于「每天 01:00 自动同步」

⚠️ **服务器上默认是关闭的。**

自动同步依赖 `ego-browser`（一个能操作「已登录生意经」的浏览器），
服务器通常没有图形界面，也没有登录态，所以跑不了。

启动时如果你看到：

```
 数据同步: 未启用（这台机器上没有 ego-browser）
           请用【导入数据】上传从生意经导出的 Excel
```

就是这个原因 —— 这是**正常的**，不是故障。

### 服务器上没有自动同步，怎么办

三种做法，按推荐顺序：

| 做法 | 说明 |
|---|---|
| **A. 每天手动导一次**（推荐） | 在浏览器登录生意经 → 导出近30天 xlsx → 在工作台【导入数据】上传。全程 2 分钟 |
| **B. 本机同步 + 上传** | 在这台 Mac 上保留一份工作台，每天 01:00 自动同步，然后把 `data/inbox/` 里的文件传上去 |
| **C. 服务器上也装 ego** | 需要图形环境（Xvfb 也行）+ 首次扫码登录，维护成本高，不建议 |

如果后面想让服务器也能自动同步，跟我说，我评估一下用无头浏览器 + cookie 导入的方案。

---

## 七、数据备份

所有数据都在 `data/` 一个目录里：

```
data/app.db                  账号 + 门店指标 + 批次记录（最重要）
data/processed/              每次导入的原始文件
data/inbox/                  待导入的收件箱
data/factory_thresholds.json 出厂阈值快照
```

**备份就一句话：**

```bash
tar czf ~/backup-$(date +%Y%m%d).tar.gz -C /opt/store-ops data
```

建议加到 crontab，每天凌晨备份一次：

```bash
0 3 * * * tar czf /root/storeops-$(date +\%Y\%m\%d).tar.gz -C /opt/store-ops data
```

---

## 八、以后要搬回本机 / 换服务器

把 `data/` 目录整个拷过去覆盖即可，**账号、密码、历史数据、原始文件全部都在**。

---

## 九、常见问题

**打不开网页**

1. `sudo systemctl status store-ops` 看进程在不在
2. `curl http://127.0.0.1:8787` 在服务器本地试能不能通
3. 本地能通、外面不通 → 安全组 / 防火墙没放行
4. 检查是不是绑了 `--local`（只允许本机）

**忘了 admin 密码**

```bash
cd /opt/store-ops
sudo -u storeops python3 - <<'EOF'
import sys; sys.path.insert(0, 'backend')
import db
db.set_password(1, 'newpass123', must_change=1)
print('admin 密码已重置为 newpass123')
EOF
sudo systemctl restart store-ops
```

**端口被占用**

```bash
sudo lsof -i:8787        # 看谁占着
PORT=9000 ./start.sh     # 或者换个端口
```

**想确认数据有没有写进去**

```bash
cd /opt/store-ops
python3 -c "import sys; sys.path.insert(0,'backend'); import db; print(db.stats()); print([p['period'] for p in db.get_periods()])"
```