Add README and documentation files
- Add project README.md with overview - Add GIT_TUTORIAL.md documentation Made-with: Cursor
This commit is contained in:
170
README.md
Normal file
170
README.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Astral3D 项目说明
|
||||
|
||||
## 项目简介
|
||||
|
||||
Astral3D 是一个基于 Vue3 + Three.js 的现代 Web 3D 编辑器，同时包含配套的 Java 后端服务。项目旨在提供一站式 3D 场景创建、管理和展示解决方案。
|
||||
|
||||
**在线演示**: [Astral 3D Editor](https://editor.astraljs.com)
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
Astral3D-Projects/
|
||||
├── Astral3D/ # 前端编辑器项目 (Vue3 + Three.js)
|
||||
│ ├── packages/ # 子包
|
||||
│ ├── common/ # 公共模块
|
||||
│ └── node_modules/ # 依赖
|
||||
│
|
||||
├── astral-service/ # 后端服务项目 (Java + SpringBoot)
|
||||
│ ├── astral-common/ # 公共模块
|
||||
│ ├── astral-core/ # 核心配置
|
||||
│ ├── astral-business/ # 业务模块
|
||||
│ ├── astral-system/ # 系统模块
|
||||
│ ├── astral-web/ # Web 层
|
||||
│ └── static/ # 静态资源
|
||||
│
|
||||
└── docs/ # 文档目录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
### 前端 (Astral3D)
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| Vue | 3.5.22 | 渐进式前端框架 |
|
||||
| Three.js | r176 | 3D 渲染引擎 |
|
||||
| Cesium | 1.107.0 | 地理信息系统 |
|
||||
| Naive UI | 2.43.1 | UI 组件库 |
|
||||
| UnoCSS | 0.46.5 | 原子化 CSS |
|
||||
|
||||
### 后端 (AstralService)
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| Java | 8 | 编程语言 |
|
||||
| Spring Boot | 2.7.18 | Web 框架 |
|
||||
| MyBatis Plus | - | ORM 框架 |
|
||||
| MySQL | - | 数据库 |
|
||||
| WebSocket | - | 实时通信 |
|
||||
|
||||
---
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 前端功能
|
||||
|
||||
- **多格式模型支持**: 30+ 模型格式（GLTF/OBJ/FBX/GLB/RVT/IFC 等）
|
||||
- **BIM 模型轻量化**: RVT/IFC 文件浏览器端展示
|
||||
- **CAD 图纸解析**: DWG/DXF 文件解析和展示
|
||||
- **场景管理**: 分包存储与动态加载
|
||||
- **动画编辑器**: 内置动画制作工具
|
||||
- **插件系统**: 扩展能力支持
|
||||
- **脚本运行时**: 脚本化业务逻辑
|
||||
- **粒子系统**: 视觉效果增强
|
||||
- **天气系统**: 场景环境模拟
|
||||
- **云存储集成**: 又拍云 USS 支持
|
||||
- **资源中心**: 统一资源管理
|
||||
|
||||
### 后端功能
|
||||
|
||||
- **用户认证**: 用户注册登录
|
||||
- **场景管理**: 场景 CRUD 操作
|
||||
- **资产管理**: 资源上传、存储、加载
|
||||
- **文件转换**: CAD DWG 转 DXF
|
||||
- **WebSocket**: 实时通信支持
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 前端开发
|
||||
|
||||
```bash
|
||||
# 进入前端项目
|
||||
cd Astral3D
|
||||
|
||||
# 使用 nvm 切换 Node 版本
|
||||
nvm use 23.11.0
|
||||
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 构建 SDK
|
||||
pnpm run sdk:build
|
||||
|
||||
# 启动开发服务器
|
||||
pnpm run editor:dev
|
||||
```
|
||||
|
||||
### 后端服务
|
||||
|
||||
```bash
|
||||
# 进入后端项目
|
||||
cd astral-service
|
||||
|
||||
# 配置数据库
|
||||
# 修改 astral-web/src/main/resources/application-dev.yml
|
||||
|
||||
# 方式一：IDEA 直接运行
|
||||
# 运行 AstralWebApplication 类
|
||||
|
||||
# 方式二：Maven 运行
|
||||
mvn spring-boot:run
|
||||
|
||||
# 方式三：打包运行
|
||||
mvn clean package
|
||||
cd astral-web/target
|
||||
java -jar astral-web-exec.jar
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据库配置
|
||||
|
||||
1. 创建 MySQL 数据库
|
||||
2. 导入表结构：`static/sql/astral_3d.sql`
|
||||
3. 修改配置文件中的数据库连接信息
|
||||
|
||||
---
|
||||
|
||||
## 文件存储配置
|
||||
|
||||
支持两种存储方式：
|
||||
|
||||
- **本地存储 (local)**: 保存在项目 static 文件夹
|
||||
- **又拍云存储 (upyun)**: 云端存储
|
||||
|
||||
---
|
||||
|
||||
## 文档目录
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [GIT_TUTORIAL.md](../GIT_TUTORIAL.md) | Git 操作教程 |
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目基于 Apache 2.0 许可证开源，详细内容请参阅 [LICENSE](../Astral3D/LICENSE) 文件。
|
||||
|
||||
---
|
||||
|
||||
## 相关链接
|
||||
|
||||
- [在线演示](https://editor.astraljs.com)
|
||||
- [文档中心](http://editor-doc.astraljs.com/)
|
||||
- [后端仓库](https://github.com/yx8663/astral-service)
|
||||
- [前端仓库](https://github.com/mlt131220/Astral3D)
|
||||
|
||||
---
|
||||
|
||||
## 交流社区
|
||||
|
||||
- QQ 交流群：1040320579
|
||||
- 微信：联系开发者（仅限商务）
|
||||
364
docs/GIT_TUTORIAL.md
Normal file
364
docs/GIT_TUTORIAL.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Git 提交操作教程
|
||||
|
||||
本教程适用于 Astral3D 项目，包含日常开发中常用的 Git 操作流程。
|
||||
|
||||
---
|
||||
|
||||
## 基础配置
|
||||
|
||||
首次使用需配置用户信息（已完成）：
|
||||
|
||||
```bash
|
||||
git config user.name "用户名"
|
||||
git config user.email "邮箱"
|
||||
```
|
||||
|
||||
查看配置：
|
||||
|
||||
```bash
|
||||
git config --list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 远程仓库
|
||||
|
||||
项目远程仓库地址：`http://code-server:3000/lyf/Astral3D.git`
|
||||
|
||||
查看远程仓库：
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常用操作流程
|
||||
|
||||
### 1. 拉取最新代码
|
||||
|
||||
```bash
|
||||
# 拉取远程最新代码并合并到当前分支
|
||||
git pull origin master
|
||||
|
||||
# 或者使用 fetch + rebase
|
||||
git fetch origin
|
||||
git rebase origin/master
|
||||
```
|
||||
|
||||
### 2. 查看当前状态
|
||||
|
||||
```bash
|
||||
# 查看工作区状态
|
||||
git status
|
||||
|
||||
# 查看简略状态
|
||||
git status -s
|
||||
```
|
||||
|
||||
### 3. 查看文件变更
|
||||
|
||||
```bash
|
||||
# 查看未暂存的变更
|
||||
git diff
|
||||
|
||||
# 查看已暂存的变更
|
||||
git diff --cached
|
||||
|
||||
# 查看具体文件的变更
|
||||
git diff filename.java
|
||||
|
||||
# 查看最近几次提交
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
### 4. 暂存文件
|
||||
|
||||
```bash
|
||||
# 暂存单个文件
|
||||
git add filename.java
|
||||
|
||||
# 暂存多个文件
|
||||
git add file1.java file2.java
|
||||
|
||||
# 暂存所有变更
|
||||
git add .
|
||||
|
||||
# 暂存所有 .java 文件
|
||||
git add *.java
|
||||
|
||||
# 暂存目录
|
||||
git add src/
|
||||
```
|
||||
|
||||
### 5. 取消暂存
|
||||
|
||||
```bash
|
||||
# 取消所有暂存
|
||||
git reset
|
||||
|
||||
# 取消单个文件暂存
|
||||
git reset filename.java
|
||||
```
|
||||
|
||||
### 6. 撤销修改
|
||||
|
||||
```bash
|
||||
# 撤销未暂存的修改（危险操作）
|
||||
git checkout -- filename.java
|
||||
|
||||
# 撤销所有未暂存的修改
|
||||
git checkout -- .
|
||||
|
||||
# 撤销已暂存的修改
|
||||
git reset HEAD filename.java
|
||||
git checkout -- filename.java
|
||||
```
|
||||
|
||||
### 7. 提交变更
|
||||
|
||||
```bash
|
||||
# 提交已暂存的变更
|
||||
git commit -m "提交说明"
|
||||
|
||||
# 提交并添加说明（会打开编辑器）
|
||||
git commit
|
||||
|
||||
# 修改最后一次提交（还没推送到远程）
|
||||
git commit --amend -m "新的提交说明"
|
||||
|
||||
# 将暂存和提交合并为一步（适合小改动）
|
||||
git commit -am "提交说明"
|
||||
```
|
||||
|
||||
### 8. 推送到远程
|
||||
|
||||
```bash
|
||||
# 推送到远程仓库
|
||||
git push origin master
|
||||
|
||||
# 第一次推送并设置上游分支
|
||||
git push -u origin master
|
||||
|
||||
# 简化写法（已设置上游分支后）
|
||||
git push
|
||||
```
|
||||
|
||||
### 9. 查看提交历史
|
||||
|
||||
```bash
|
||||
# 查看详细提交历史
|
||||
git log
|
||||
|
||||
# 查看简略历史
|
||||
git log --oneline
|
||||
|
||||
# 查看最近5条
|
||||
git log --oneline -5
|
||||
|
||||
# 查看分支合并历史
|
||||
git log --graph --oneline --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 分支操作
|
||||
|
||||
### 1. 查看分支
|
||||
|
||||
```bash
|
||||
# 查看本地分支
|
||||
git branch
|
||||
|
||||
# 查看远程分支
|
||||
git branch -r
|
||||
|
||||
# 查看所有分支
|
||||
git branch -a
|
||||
```
|
||||
|
||||
### 2. 创建分支
|
||||
|
||||
```bash
|
||||
# 基于当前分支创建新分支
|
||||
git branch feature-xxx
|
||||
|
||||
# 基于 master 创建新分支
|
||||
git branch feature-xxx master
|
||||
```
|
||||
|
||||
### 3. 切换分支
|
||||
|
||||
```bash
|
||||
# 切换到分支
|
||||
git checkout feature-xxx
|
||||
|
||||
# 创建并切换到新分支
|
||||
git checkout -b feature-xxx
|
||||
|
||||
# 切换到上一个分支
|
||||
git checkout -
|
||||
```
|
||||
|
||||
### 4. 合并分支
|
||||
|
||||
```bash
|
||||
# 切换到 master 分支
|
||||
git checkout master
|
||||
|
||||
# 合并 feature-xxx 分支到当前分支
|
||||
git merge feature-xxx
|
||||
|
||||
# 使用 rebase 合并（保持线性历史）
|
||||
git rebase feature-xxx
|
||||
```
|
||||
|
||||
### 5. 删除分支
|
||||
|
||||
```bash
|
||||
# 删除本地分支（已合并）
|
||||
git branch -d feature-xxx
|
||||
|
||||
# 强制删除本地分支
|
||||
git branch -D feature-xxx
|
||||
|
||||
# 删除远程分支
|
||||
git push origin --delete feature-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 标签操作
|
||||
|
||||
### 1. 创建标签
|
||||
|
||||
```bash
|
||||
# 创建轻量标签
|
||||
git tag v1.0.0
|
||||
|
||||
# 创建附注标签（带说明）
|
||||
git tag -a v1.0.0 -m "版本说明"
|
||||
|
||||
# 为历史提交打标签
|
||||
git tag -a v1.0.0 commitid -m "版本说明"
|
||||
```
|
||||
|
||||
### 2. 查看和推送标签
|
||||
|
||||
```bash
|
||||
# 查看标签
|
||||
git tag
|
||||
|
||||
# 查看标签详情
|
||||
git show v1.0.0
|
||||
|
||||
# 推送标签到远程
|
||||
git push origin v1.0.0
|
||||
|
||||
# 推送所有标签
|
||||
git push origin --tags
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 解决冲突
|
||||
|
||||
### 1. 识别冲突
|
||||
|
||||
```bash
|
||||
# 查看冲突文件
|
||||
git status
|
||||
```
|
||||
|
||||
冲突文件会显示为 `both modified`
|
||||
|
||||
### 2. 手动解决冲突
|
||||
|
||||
打开冲突文件，会看到类似以下标记：
|
||||
|
||||
```
|
||||
<<<<<<< HEAD
|
||||
当前分支的代码
|
||||
=======
|
||||
合并进来的代码
|
||||
>>>>>>> branch-name
|
||||
```
|
||||
|
||||
手动修改后：
|
||||
|
||||
```bash
|
||||
# 标记冲突已解决
|
||||
git add filename.java
|
||||
|
||||
# 完成合并
|
||||
git commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 暂存操作（Stash）
|
||||
|
||||
用于临时保存未提交的更改：
|
||||
|
||||
```bash
|
||||
# 暂存当前更改
|
||||
git stash
|
||||
|
||||
# 暂存并添加说明
|
||||
git stash save "临时保存说明"
|
||||
|
||||
# 查看暂存列表
|
||||
git stash list
|
||||
|
||||
# 恢复暂存的更改
|
||||
git stash pop
|
||||
|
||||
# 删除暂存
|
||||
git stash drop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 代理问题
|
||||
|
||||
如果推送时遇到 503 错误，尝试设置代理排除：
|
||||
|
||||
```bash
|
||||
export no_proxy="code-server,192.168.1.72,localhost,127.0.0.1"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### 2. 每次推送都要输入密码
|
||||
|
||||
可以配置凭证缓存：
|
||||
|
||||
```bash
|
||||
# 缓存凭证 15 分钟
|
||||
git config --global credential.helper cache
|
||||
|
||||
# 缓存更长时间（单位：秒）
|
||||
git config --global credential.helper 'cache --timeout=3600'
|
||||
```
|
||||
|
||||
### 3. 查看配置
|
||||
|
||||
```bash
|
||||
# 查看所有配置
|
||||
git config --list
|
||||
|
||||
# 查看特定配置
|
||||
git config user.name
|
||||
git config remote.origin.url
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **提交前先拉取**：每次提交前先 `git pull origin master`
|
||||
2. **保持提交原子性**：一个提交只做一件事
|
||||
3. **提交说明清晰**：说明改了什么，为什么改
|
||||
4. **不要提交敏感信息**：不要提交密码、密钥等
|
||||
5. **使用 .gitignore**：排除不需要跟踪的文件（如 target/、.idea/）
|
||||
Reference in New Issue
Block a user