从零搭建本地可运行元宇宙档案服务 零门槛实操落地指南

前置环境准备

安装Docker与Docker Compose

本方案基于容器化部署，无需手动安装各类语言依赖，只要你的设备是Windows/macOS/Linux任意系统、能正常联网即可，按照对应系统说明完成安装：

• Windows系统：直接下载安装包：https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe，双击运行按提示完成安装即可。

• macOS系统：直接下载安装包：https://desktop.docker.com/mac/main/amd64/Docker.dmg，拖拽安装即可。

• Linux系统：复制执行以下一键安装命令，完成后自动配置好环境：

  ``` curl -fsSL https://get.docker.com | bash -s docker && systemctl start docker && curl -L "https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose ```

安装完成后打开命令行，执行以下命令验证，输出版本号即说明安装成功：

``` docker -v && docker-compose -v ```

一键部署元宇宙档案服务

创建工作目录

在本地任意位置打开命令行，执行以下命令创建工作目录并进入：

``` mkdir meta-archive && cd meta-archive ```

编写编排配置文件

在刚创建的meta-archive文件夹内，新建一个名为docker-compose.yml的文件，将以下内容完整复制进去，所有参数已经预配置好，不需要额外修改：

``` version: '3.8' services: ipfs: image: ipfs/go-ipfs:latest volumes: - ./ipfs-data:/data/ipfs ports: - "5001:5001" - "8080:8080" restart: unless-stopped meta-archive-backend: image: openmeta/meta-archive-backend:v1.0.0 ports: - "3000:3000" environment: - IPFS_NODE_URL=http://ipfs:5001 - JWT_SECRET=meta_archive_local_secret_2024 depends_on: - ipfs restart: unless-stopped meta-archive-frontend: image: openmeta/meta-archive-frontend:v1.0.0 ports: - "8090:80" depends_on: - meta-archive-backend restart: unless-stopped ```

注意事项：如果你的本地8090、3000、5001、8080任意端口被占用，只需要把配置文件中对应端口的左侧数字改成其他未占用端口即可，比如将8090改成8091。

启动服务并验证

在meta-archive目录的命令行中，执行以下命令启动服务：

``` docker-compose up -d ```

命令执行后会自动拉取所需镜像，根据网络速度不同，等待1-5分钟即可完成启动。执行以下命令验证启动状态：

``` docker-compose ps ```

如果输出结果中，ipfs、meta-archive-backend、meta-archive-frontend三个服务的STATUS列显示为Up，即说明部署启动成功。

基础实操使用指南

登录管理后台

打开本地任意浏览器，在地址栏输入 http://localhost:8090（如果修改过端口换成对应端口），即可进入元宇宙档案服务管理页，默认管理员账号密码为：

账号：admin@meta-archive.local
密码：admin123

第一次登录后请立即进入个人中心修改默认密码，避免权限泄露。

上传元宇宙数字档案

• 登录后点击左侧菜单栏的「档案上传」，进入上传页

• 选择需要归档的元宇宙资产文件，支持NFT元数据、虚拟地块凭证、数字藏品、3D场景模型等所有格式文件，单文件最大支持10GB

• 填写档案基础信息：填写档案名称、选择分类（数字藏品/虚拟地产/虚拟身份/其他）、添加描述，勾选「公开」即可生成可分享链接，勾选「私有」仅自己可查看

• 点击「确认上传」，等待上传完成后，系统会自动生成档案的IPFS CID哈希，这是该档案的全球唯一标识，永久有效不会丢失。

档案检索与分享

点击左侧菜单栏「档案管理」，可以通过名称、标签、分类快速检索已归档内容，找到对应档案后点击「分享」按钮，即可生成可外部访问的分享链接，对方不需要搭建服务就能直接查看档案内容。

日常维护与常见问题

基础维护操作

• 停止服务：进入meta-archive目录执行 docker-compose down

• 重启服务：进入meta-archive目录执行 docker-compose restart

• 数据备份：所有档案数据都存储在meta-archive目录下的ipfs-data文件夹中，备份整个meta-archive文件夹即可完整迁移服务，放到其他设备直接启动即可使用。

常见问题解决

• 无法访问前端页面：检查Docker是否正常运行，检查配置的端口是否被占用，修改端口后重新启动即可。

• 文件上传失败：执行 docker-compose logs ipfs 查看IPFS节点日志，多数情况为本地存储空间不足，清理多余文件即可。

• 镜像拉取失败：国内网络拉取Docker镜像速度慢或失败时，配置Docker国内镜像源后重新执行启动命令即可。