English Documentation

一个医学 3D 模型展示与分享系统。项目以 PHP + MySQL + Three.js 为核心，支持 病例管理、STL 上传、服务端异步预处理为 GLB、前台安全查看、Docker 一键部署。

link: https://3d.czsyyy.cn/v?token=cddaa9000ca8fb4ed363a4c8457ced10 password: 1234

　

　

---

• 病例管理后台：创建、编辑、删除病例，统一管理访问策略与模型资产
• STL 上传与异步预处理：上传后自动由服务端预处理生成 GLB 展示资产，前台不再直接加载原始 STL
• 前台安全访问：支持 none / password / patient_name 三种访问验证模式
• 多模型 3D Viewer：支持旋转、平移、缩放、背景切换、模型显隐与交互式调色
• 前后台双端口隔离：适合“前台可公网访问、后台仅内网访问”的医院网络环境
• Docker 部署：提供开发态与生产态两套编排
• Node.js 预处理 Worker：在容器内自动处理 STL → GLB 队列

---

• 后端：PHP / PDO MySQL
• 数据库：MySQL 8
• 前端 3D：Three.js、GLTFLoader
• 预处理：Node.js、three
• 网关：Nginx
• 进程管理：supervisord
• 部署：Docker Compose

---

.
├─ app/                      PHP 业务代码
├─ bootstrap/                启动、辅助函数、自动加载
├─ config/                   配置文件
├─ database/migrations/      初始化迁移 SQL
├─ docker/php/               PHP + Nginx + Worker 容器定义
├─ install/                  首次安装引导
├─ public/assets/            前端静态资源
├─ scripts/                  Worker 与 STL→GLB 处理脚本
└─ storage/uploads/          原始 STL 与展示 GLB 资产

---

使用 docker-compose.yml：

docker compose up -d --build

---

容器启动后，访问安装页完成初始化：

• 前台安装入口：http://<host>:8098/install/

安装流程由 install/install.php 负责，自动执行：

• 创建数据库
• 执行 database/migrations
• 创建管理员
• 写入 .env
• 生成 storage/installed.lock

---

当前默认设计：

• 前台：8098
• 后台：8099

Nginx 双入口定义位于 docker/php/nginx.conf 与 docker/php/nginx.conf

推荐部署策略：

• 前台端口可公网开放
• 后台端口仅内网开放
• 通过路由器端口转发或反向代理，仅暴露前台流量

---

项目支持配置多套分享通道，并由管理员在后台手动选择生成：

• 内网地址
• 外网局域网 IP
• 公网域名

相关配置文件：config/share_channels.php

默认可通过环境变量控制：

• APP_FRONT_URL
• APP_SHARE_PUBLIC_URL
• APP_SHARE_DEFAULT_CHANNEL

后台生成链接与二维码时，不再完全依赖当前访问 Host，而是由管理员显式选择分享通道。

---

1. 管理员上传 STL
2. 后端保存原始 STL
3. 写入模型记录，状态置为 pending
4. Worker 脚本 scripts/process-model-queue.php 扫描待处理模型
5. Node 脚本 scripts/stl-to-glb.mjs 执行 STL → GLB 转换
6. 前台仅消费处理完成的 GLB 资产

• pending
• processing
• ready
• failed

前台在 GLB 尚未全部就绪前会显示等待提示，不会回退加载原始 STL。

---

首次部署时会自动执行 database/migrations 下的 SQL 文件。

若你是在已有数据库上升级到当前版本，请根据 database/migrations/ 中的 SQL 文件与现网数据库状态自行整理升级脚本。

---

参考模板：.env.example

常用项包括：

• APP_NAME
• APP_FRONT_URL
• APP_ADMIN_URL
• APP_SHARE_PUBLIC_URL
• DB_HOST
• DB_PORT
• DB_NAME
• DB_USER
• DB_PASS

---

后台入口位于 docker/php/nginx.conf，推荐只允许内网访问。

如果病例使用“无需验证”模式，分享链接泄露后风险更高。生产环境更推荐默认使用 password 验证模式。

模型下载接口由 ViewerController.modelFile() 控制。若接入 CDN，请避免对私有模型下载接口做公共缓存。

安装完成后建议通过网关或 Nginx 规则限制 /install/ 暴露。

---

本项目采用 Apache 2.0 许可证。