首次提交: OnebotCatalog 项目代码与文档（含 NX 按需生成服务二期、后台、一键启动）

viewer/STEPViewer/部署说明.md

@@ -0,0 +1,95 @@
+# 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=`