PartNet 标注系统配置参考

一、系统概述

标注系统仓库

PartNet 标注系统是一个用于 3D 部件标注的 Web 工具，包含后端（Node.js + MySQL）和前端（基于 Browserify 构建）两部分。本指南汇总了流程与问题后由 ai 整理生成，如遇到的问题指南无法解决，请返回仓库阅读 README.md 文档或询问 ai 解决。指南将帮助您在 Ubuntu 系统上完整部署该系统，并汇总了部署过程中可能遇到的常见问题及解决方案。

二、环境要求

  • 操作系统：Ubuntu 18.04、20.04 为宜（22.04、24.04 等版本也可）
  • 软件依赖：
    • Node.js（建议使用 nvm 安装 v10 LTS，因为项目依赖较老）
    • MySQL 5.7（根据不同 Ubuntu 版本选择安装方式）
    • Python 3（用于 remesh 脚本）
    • Git、curl、wget、build-essential、cmake
    • Manifold 工具（用于模型修复，需编译）

三、安装前准备

先把 github 仓库拉取到本地。

1. 更新系统

sudo apt update && sudo apt upgrade -y

2. 安装基础工具

sudo apt install -y curl wget git build-essential cmake

3. 检查并清理代理（如之前设置过）

如果您的网络曾经配置过 HTTP 代理，可能导致 curl、npm 等工具无法正常工作，请先清除代理环境变量，并检查 ~/.bashrc 中是否有永久代理设置。

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
# 编辑 ~/.bashrc，删除或注释掉 export http_proxy=... 等行

四、安装 Node.js 环境（使用 nvm）

1. 安装 nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash
source ~/.bashrc

2. 安装 Node.js v10（项目兼容版本）

nvm install 10
nvm use 10
node -v   # 应显示 v10.x.x

注意：如果使用更高版本（如 v14+），某些旧模块（如 sleep）可能编译失败。若遇到编译错误，请务必降级到 v10。

3. 设置默认版本

nvm alias default 10

五、安装 MySQL 5.7

根据您的 Ubuntu 版本，选择以下两种安装方式之一。

5.1 选项 A：直接安装 MySQL 5.7（适用于 Ubuntu 18.04、20.04、22.04）

Ubuntu 20.04 及以下版本可以通过添加 MySQL 官方仓库来安装 5.7 版本。对于 Ubuntu 22.04，官方仓库虽已转向 8.0，但依然可以添加 5.7 仓库进行安装（可能会遇到依赖问题，建议使用 Docker 方案）。

5.1.1 添加 MySQL APT 仓库

wget https://dev.mysql.com/get/mysql-apt-config_0.8.22-1_all.deb
sudo dpkg -i mysql-apt-config_0.8.22-1_all.deb

在配置界面选择 Ubuntu Bionic（对应 18.04）或 Ubuntu Focal（对应 20.04），然后选择 MySQL Server & Cluster，再选择 mysql-5.7，最后选择 Ok 完成。

5.1.2 更新并安装 MySQL 5.7

sudo apt update
sudo apt install -y mysql-server=5.7.* mysql-client=5.7.*

安装过程中会提示设置 root 密码，请牢记。

5.1.3 启动并验证

sudo systemctl start mysql
sudo systemctl enable mysql
mysql --version   # 应显示 5.7.x

5.2 选项 B：使用 Docker 运行 MySQL 5.7（推荐，适用于所有 Ubuntu 版本，特别是 24.04）

Ubuntu 24.04 官方源已不再提供 MySQL 5.7，使用 Docker 可以完美解决版本兼容问题，且不会污染系统环境。

5.2.1 安装 Docker

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce
sudo usermod -aG docker $USER   # 将当前用户加入 docker 组，需重新登录生效

5.2.2 配置 Docker 镜像加速器（可选，推荐）

创建 /etc/docker/daemon.json，加入以下内容（以阿里云专属加速器为例）：

{
  "registry-mirrors": ["https://<你的专属加速器地址>.mirror.aliyuncs.com"]
}

重启 Docker：sudo systemctl restart docker

5.2.3 运行 MySQL 5.7 容器

docker run --name partnet-mysql -e MYSQL_ROOT_PASSWORD=partnet-mysql -p 3306:3306 -d mysql:5.7

说明：密码可自行修改，后续配置文件中需保持一致。

5.2.4 验证容器运行

docker ps   # 应看到 partnet-mysql 状态为 Up

六、安装 Manifold 工具（用于 remesh 功能）

1. 克隆仓库并编译

cd ~
git clone https://github.com/hjwdzh/Manifold.git
cd Manifold
mkdir build && cd build
cmake .. && make

2. 安装可执行文件

sudo cp manifold /usr/local/bin/model_fixer

注意：新版 Manifold 生成的可执行文件名为 manifold，但项目脚本中调用的是 model_fixer，因此我们将其复制为 model_fixer 以保持兼容。

3. 验证安装

which model_fixer   # 应输出 /usr/local/bin/model_fixer
model_fixer --help  # 显示帮助信息

七、克隆 PartNet 标注系统代码

假设项目代码放在 /path/to/your/workspace，注意路径中避免空格与中文（或后续统一处理）。

git clone <项目仓库地址> partnet_anno_system
cd partnet_anno_system

八、配置后端（server）

1. 进入 server 目录

cd server

2. 安装 Node.js 依赖

npm install

可能遇到的问题：

  • sleep 模块编译失败：请确认 Node.js 版本为 v10。
  • 网络超时：可使用淘宝镜像 npm install --registry=https://registry.npmmirror.com。

3. 配置数据库

根据您选择的 MySQL 安装方式，执行对应的命令。

3.1 创建数据库

  • 如果使用本机安装的 MySQL：

    mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS partnet_anno_system;"

    输入密码后执行。

  • 如果使用 Docker 容器：

    docker exec -i partnet-mysql mysql -u root -ppartnet-mysql -e "CREATE DATABASE IF NOT EXISTS partnet_anno_system;"

3.2 导入表结构

  • 本机 MySQL：
    mysql -u root -p partnet_anno_system < mysql/create_table.sql
  • Docker 容器：
    docker exec -i partnet-mysql mysql -u root -ppartnet-mysql partnet_anno_system < mysql/create_table.sql

3.3 导入模型列表（如果已有数据）

  • 本机 MySQL：
    python mysql/import_into_mysql.py 127.0.0.1 root <your_password> --database partnet_anno_system
  • Docker 容器（注意密码可能需在命令中指定）：
    python mysql/import_into_mysql.py 127.0.0.1 root partnet-mysql --database partnet_anno_system

4. 复制并修改配置文件

4.1 复制模板

cp bin/www.template bin/www
cp config/server.js.template config/server.js
cp python/config.py.template python/config.py

4.2 编辑 bin/www

修改端口（可选）：

var port = normalizePort(process.env.PORT || '3000'); // 默认3000

4.3 编辑 config/server.js

设置数据库连接和代码路径：

server.HOST = 'http://localhost';
server.PORT = '3000';
server.DB_HOST = '127.0.0.1';    // 注意：无论本机还是 Docker，都用 127.0.0.1 强制 TCP 连接
server.DB_USER = 'root';
server.DB_PASSWORD = 'partnet-mysql';  // 根据你设置的密码修改
server.DB_NAME = 'partnet_anno_system';
server.CODE_DIR = '/绝对路径/partnet_anno_system/server';  // 用 pwd 命令获取

注意：如果路径中包含空格，请务必用双引号括起来，并确保后续所有调用都正确处理空格。建议将路径中的空格改为下划线，以避免转义问题。

4.4 编辑 python/config.py

设置 storage 文件夹路径：

file_storage_base_dir = '/绝对路径/partnet_anno_system/server/storage'

并确保该目录存在：

mkdir -p /绝对路径/partnet_anno_system/server/storage/{annotations,data,downloads,remesh_parts,new_parts,anno_results,screenshots}

5. 修复 remesh 脚本中的路径问题

打开 routes/remesh.js，修改调用 Python 脚本的方式，避免空格导致的错误：

const { exec } = require('child_process');
var scriptPath = path.join(server.CODE_DIR, 'python', 'process_remesh.py');
var command = `python "${scriptPath}" ${req.params.code}`;  // 给路径加双引号
exec(command, function(err, stdout, stderr) {
    // ...
});

6. 修复 Python 脚本兼容性

process_remesh.py 中包含 Python 2 的 print 语句，需要转换为 Python 3 语法。

cd server/python
2to3 -w process_remesh.py

同时，将脚本中的 os.mkdir 替换为 os.makedirs，以递归创建目录：

os.makedirs(remesh_part_dir, exist_ok=True)

7. 启动后端

npm start

看到 [ database connected ] 等日志，说明启动成功。保持终端运行。

九、配置前端（client）

1. 打开新终端，进入 client 目录

cd ../client

2. 安装 Node.js 依赖

由于 phantomjs 安装可能失败，使用 --ignore-scripts 跳过：

npm install --ignore-scripts

3. 安装额外依赖

npm install jquery bootstrap --ignore-scripts

4. 配置后端接口地址

复制模板并编辑：

cp config/backend.js.template config/backend.js

修改为：

be_config.remoteHost = 'http://localhost';
be_config.remotePort = '3000';

5. 构建前端

./build.sh

如果构建成功，会在 build/ 下生成 PartNet.bundle.js。

常见问题：

  • 构建出的文件名可能带有 \r 换行符，导致浏览器 404。此时需重命名文件：
    mv build/'PartNet.bundle.js'$'\r' build/PartNet.bundle.js

十、启动整个系统

1. 确保后端已在运行（见八.7）

2. 打开浏览器，访问 http://localhost:3000

3. 注册普通用户或使用管理员账号（管理员需手动在数据库添加）

十一、常见问题及解决方案（汇总）

1. 网络代理问题

  • 现象：curl、git、npm install 等命令无法连接外网，报错 Failed to connect to 127.0.0.1 port 7890。
  • 原因：系统中设置了 HTTP 代理环境变量。
  • 解决：
    unset http_proxy https_proxy
    并检查 ~/.bashrc，删除或注释掉 export http_proxy=... 等行。

2. nvm 安装后 nvm 命令找不到

  • 原因：未重新加载 shell 配置文件。
  • 解决：执行 source ~/.bashrc 或重新打开终端。

3. npm 安装时 sleep 模块编译失败

  • 现象：大量 C++ 编译错误，如 error: no matching function for call。
  • 原因：Node.js 版本过高，sleep 模块仅支持旧版。
  • 解决：使用 nvm 切换到 Node.js v10。

4. Docker 拉取镜像失败

  • 现象：Error response from daemon: Get https://registry-1.docker.io/v2/...: net/http: TLS handshake timeout 或 403 Forbidden。
  • 原因：网络问题或镜像源限制。
  • 解决：
    • 配置国内镜像加速器（阿里云、中科大、清华等）。
    • 如果使用阿里云专属加速器仍报 403，请检查账号或更换其他源。

5. MySQL 连接问题

  • 现象：服务器日志显示 [ connect error ]，connection.query 报 undefined。
  • 原因：MySQL 服务未运行，或配置文件中的 DB_HOST 使用了 localhost 而非 127.0.0.1。
  • 解决：
    • 本机安装：sudo systemctl start mysql
    • Docker 安装：docker start partnet-mysql
    • 确保 config/server.js 中 DB_HOST 为 127.0.0.1。

6. 导入 SQL 文件时提示 Unknown database 'partnet_anno_system'

  • 原因：数据库未创建。
  • 解决：先创建数据库再导入（见八.3.1）。

7. 运行 Python 脚本时提示 ModuleNotFoundError: No module named 'mysql'

  • 原因：缺少 mysql-connector-python。
  • 解决：pip install mysql-connector-python 或使用 conda。

8. 前端构建后访问页面，PartNet.bundle.js 返回 404

  • 原因：client 的配置脚本 ./build.sh 会在 PartNet.bundle.js 末尾加上 \r 导致文件无法被定位。
  • 解决：
    • 重命名文件：mv build/'PartNet.bundle.js'$'\r' build/PartNet.bundle.js
    • 检查 server/app.js 中静态文件中间件配置是否正确：
      app.use('/client', express.static(path.join(__dirname, '../client')));

9. remesh 功能失败，报错找不到 model_fixer

  • 原因：Manifold 工具未安装或未添加到 PATH。
  • 解决：编译并安装 model_fixer（见第六节）。

10. remesh 功能失败，报错 FileNotFoundError: No such file or directory: '.../remesh_parts'

  • 原因：Python 脚本中使用 os.mkdir 但父目录不存在。
  • 解决：将脚本中的 os.mkdir 替换为 os.makedirs(..., exist_ok=True)。

11. remesh 功能失败，报错 SyntaxError: Missing parentheses in call to 'print'

  • 原因：Python 脚本使用了 Python 2 的 print 语句，但系统默认 Python 3。
  • 解决：用 2to3 工具转换脚本，或手动将 print ... 改为 print(...)。

12. 路径中包含空格导致的各类问题

  • 现象：python: can't open file，路径被截断。
  • 解决：
    • 将所有涉及路径的命令都使用双引号包裹变量，例如 python "${scriptPath}"。
    • 或者将项目目录中的空格改为下划线（需同时修改所有配置文件中的路径），并确保文件系统目录名也相应更改。

13. storage 文件夹位置不对

  • 解决：storage 放在 server 目录下

14. 若使用 docker，每次启动服务器前需先用 docker 启动 mysql5.7

十二、最终验证

  1. 访问 http://localhost:3000，能正常显示登录页面。
  2. 注册用户并登录，能看到模型列表（如果已导入）。
  3. 点击某个模型进入标注页面，应能显示 3D 模型和部件树。
  4. 尝试进行部件切割（remesh），应能成功生成新部件。
posted @ 2026-03-16 19:50  Semorius  阅读(1)  评论(0)    收藏  举报