# STEP 3D 查看器部署说明

## 〇、群晖 NAS 专用步骤（ftp.ruiguo.wang）

1. **套件中心安装**：Web Station + PHP 8.x（DSM 7）
2. **传文件**：File Station → 找到网站根目录（对应 https://ftp.ruiguo.wang/3D/web/ 的目录）
   → 把 `STEPViewer` 整个文件夹上传到 `3D/web/` 下
3. **开 PHP**：Web Station → 脚本语言设置 → 确认 PHP 8.x 已启用（默认启用；
   如果用虚拟主机方式建站，需在该站点设置里选择 PHP 版本）
4. **改密钥**：`api/upload.php`、`api/token.php`、`api/model.php` 里的 `$SECRET`
   已经改成随机字符串（三处一致），如需自行更换请保持一致
5. **私有目录（已预设，nginx 下最省事）**：
   - `api/upload.php` 和 `api/model.php` 已预设
     `$PRIVATE_DIR = '/volume1/stepviewer_private';`（路径不对就改成实际路径）
   - File Station 在 Web 目录外建这个文件夹（右键 web 文件夹同级 → 新建），
     并给 `http` 用户组读写权限
   - 上传的加密模型直接存这里，**Web 目录里根本没有模型文件，谁都下载不到**
   - 你现有的 `assets/models/*.stp` 也建议移到这个私有目录，
     之后嵌入链接用 `?file=LZ01001001_H100_2mm.stp`（只写文件名即可）
   - 留在 Web 目录里的文件（如 samples/ 样例）按原路径仍可打开（读取端自动退回站内），
     但**它们仍可被直链下载**——要保护的文件必须移进私有目录
6. **可选——nginx 开 gzip（大幅加速远程打开）**：
   模型上传/下载已内置 gzip（STEP 文本可压到约 1/6，自动生效）；
   再做这一步可让 7.6MB 的 wasm 引擎也压缩传输（约 2.9MB）。SSH 编辑
   Web Station 站点配置，在 server 块加：
   ```
   gzip on;
   gzip_types application/wasm application/javascript text/css text/plain;
   gzip_min_length 1024;
   ```
   （查看器会自动判断：浏览器 fetch 对 gzip 响应透明解压，无需任何前端配置）
7. **验证**：见下方「验证清单」

> 群晖 Web Station 默认 nginx，`.htaccess` 不生效——用上面的私有目录方案替代。
> 若坚持模型文件留在 Web 目录，需 SSH 加 nginx 规则：
> `location ~* \.(stp|step|enc)$ { return 403; }`（控制面板→终端机开 SSH）

## 一、目录结构（整个文件夹上传，缺一不可）

## 一、目录结构（整个文件夹上传，缺一不可）

```
STEPViewer/
├── index.html / app.js / style.css   ← 页面与逻辑
├── embed_demo.html                   ← 嵌入示例（可不传）
├── libs/                             ← three.js + occt WASM 引擎（约 8MB）
├── icons/                            ← 界面图标
├── samples/                          ← 测试模型（可不传）
├── uploads/                          ← 上传的加密模型（自动创建）
├── api/                              ← PHP 接口（虚拟主机用）
└── .htaccess                         ← 防直链（Apache 用）
```

## 二、方案 A：虚拟主机 / PHP 空间（最常见）

1. 用 FTP 客户端（如 FileZilla）把整个 `STEPViewer` 文件夹上传到网站目录
   例如：`https://ftp.ruiguo.wang/3D/web/STEPViewer/`
2. 确保主机支持 PHP 7+（`api/` 里的三个接口就是 PHP 写的）
3. 修改 `api/upload.php`、`api/token.php`、`api/model.php` 里的 `$SECRET` 为随机长字符串
4. 确认主机是 Apache（.htaccess 生效）→ 模型文件自动禁止直链；
   如果是 Nginx，需要在配置里加等价规则（联系主机商或参考下方）
5. 把模型文件放到查看器目录内（整个 STEPViewer 文件夹一起传，如 `STEPViewer/models/xxx.stp`），
   嵌入地址：`/STEPViewer/index.html?file=models/xxx.stp&embed=1`
   ⚠️ 启用防下载后（.htaccess 或 nginx 403 规则），`../` 这种逃出查看器目录的路径会被
   令牌通道拒绝（防目录穿越），模型必须放在查看器目录内；用私有目录方案（§〇）时只写文件名。

**验证清单：**
- 浏览器打开 index.html 能加载模型 ✓
- 直接访问 .stp 文件 → 403/拒绝 ✓
- 拖入本地文件 → 状态栏显示「已上传」→ 嵌入链接可用 ✓

## 三、方案 B：自己的服务器（VPS/云主机，可跑 Python）

1. 上传 `STEPViewer` 整个目录
2. 把开发用的 `nds_server_step.py` 传上去，修改：
   - `SECRET` 为随机长字符串
   - 监听 `0.0.0.0:8910`（对外服务）
3. 用 systemd / pm2 / nohup 常驻运行
4. Nginx 反代（可选，便于 80/443 端口）：
   ```
   location /3D/web/STEPViewer/ {
       proxy_pass http://127.0.0.1:8910/;
       proxy_set_header Host $host;
       client_max_body_size 500m;
   }
   ```
   注意 Nginx 下需额外禁止 .stp/.step/.enc 直链（Python 服务本身已 403 拦截 ✓）

## 四、常见问题

- **模型打不开**：检查 `libs/occt-import-js.wasm` 是否上传完整（7.6MB），服务器 `.wasm` 的 MIME 应为 `application/wasm`；开了 nginx gzip 后不影响（浏览器自动解压）
- **打开慢**：模型传输已内置 gzip（约省 84% 流量）；wasm 引擎首次加载需下载 7.6MB，之后走浏览器缓存；群晖上建议按第〇节第 6 步给 nginx 开 gzip
- **上传失败提示**：说明接口没通（PHP 环境缺失或路径不对），模型仍可本地查看
- **嵌入链接别人打不开**：确认用的是线上域名而非 127.0.0.1
- **跨域加载（?url=）**：目标服务器必须允许 CORS，否则请用同源 `?file=`