# 本地测试与云服务器部署

项目主页、完整网页 Wiki、购买配置页和素材都在 `website/public/` 中。提交订单和管理发货另需运行订单服务。纯静态站可浏览商品和选配件。

## 先在本地看

在仓库根目录启动：

```powershell
.\scripts\Start-Site.ps1
```

打开 `http://127.0.0.1:8765/`；Wiki 是 `http://127.0.0.1:8765/wiki/Home.html`。脚本在后台运行服务，关闭终端后仍可查看。进程记录和日志在 `artifacts/local-server/`。

购买页在 `/buy.html`，订单后台在 `/admin.html`。打开 `artifacts/shop/admin-key.txt`，把其中的访问密钥填到后台。订单保存到同目录的 `orders.sqlite3`，重启后仍可查看。改动服务端代码后，先停止再启动服务。

提交订单后会显示待付款。支付宝尚待接入。后台可在核对实际到账后填入收款凭证，把订单转为待发货。寄出后填快递公司和运单号，即可保存发货记录。

停止服务：

```powershell
.\scripts\Stop-Site.ps1
```

端口已占用时，用 `-Port 8766` 启动，停止时使用相同端口。脚本不会关闭占用端口的其他程序。Windows 如果限制本地脚本执行，也可以直接运行：

```sh
python scripts/serve_site.py --host 127.0.0.1 --port 8765
```

直接运行时按 Ctrl+C 停止。服务默认只监听本机，支持视频范围请求和拖动进度；不存在的文件返回 404。

修改网页后重新运行 `python scripts/build_site.py`，刷新浏览器即可。服务只读取生成目录，没把工作区、日志或 `.git` 当作网站根目录。

## 放到已有的云服务器

生成部署包：

```sh
python scripts/prepare_server_bundle.py
```

`release/cloud-server.zip` 包含静态站、订单服务和 Nginx 配置示例。把 `site/` **里面的全部内容**上传到网站目录，例如 `/var/www/hall-sensor-lab/`。目录中应直接看到 `index.html` 和 `wiki/`。

已有 Nginx 站点时，把网站根目录指到这个目录，并参考随包配置设置文件类型和 404。使用独立 server 块时，先把 `server_name _` 换成实际域名或公网 IP，再将配置放进 Nginx 的 `http {}` 包含目录；例子使用端口 80。现有站点的 HTTPS 入口可以继续使用，证书和域名按该服务器的配置处理。

在服务器检查并重载：

```sh
sudo nginx -t
sudo systemctl reload nginx
```

配置中 `try_files` 检查真实文件，不把错误地址转成主页；标准静态文件响应支持视频字节范围请求。具体指令可查 [Nginx 的 root、try_files 和 types 文档](https://nginx.org/en/docs/http/ngx_http_core_module.html)。

随包配置为 HTML、CSS、JavaScript、JSON 等文本启用 gzip，减小内嵌模型页面的传输体积；MP4 不再次压缩。配置依据 [Nginx gzip 模块文档](https://nginx.org/en/docs/http/ngx_http_gzip_module.html)，实际响应是否带 `Content-Encoding: gzip` 可在云服务器上线后查看浏览器网络面板。

## 启用订单服务

将 `backend/` 放到网站目录之外，例如 `/opt/hall-lab/backend/`。用 Python 3.10 或更新版本运行下面的命令，换成实际 HTTPS 域名。运行账号需要有订单数据目录的读写权限。

```sh
HALL_SHOP_DATA=/var/lib/hall-lab python3 /opt/hall-lab/backend/serve_site.py \
  --document-root /var/www/hall-sensor-lab --host 127.0.0.1 --port 8765 \
  --shop-origin https://shop.example.com
```

把随包的 `shop.nginx.conf` 包含到同域名的 HTTPS server 块中，重载 Nginx 后访问购买页和后台。对外运行时由服务器的进程管理工具保持订单服务运行。请将密钥与订单数据库保存在独立的私有目录，并在备份时一并保留。

## 上线后点一下这些入口

- `/`：主页、原理演示、图片放大和搜索。
- `/wiki/Home.html`：完整 Wiki 导航与图纸。
- `/wiki/Animation-Library.html`：视频、字幕及三维交互入口。
- `/experiments/hall-linear-light.html`、`/experiments/hall-rotary-light.html`：模型和三路曲线。
- `downloads/hall-sensor-lab-source.zip`：项目下载。

本地测试检查的网页与部署包使用同一份 `website/public/`。云服务器的域名、端口和 HTTPS 要在实际服务器上确认；本项目不会自动修改云服务器。