1. 安装部署
  2. Mac 部署

本教程以 my-app 为例,指导你如何在 Mac 系统中本地部署和运行基于华炎魔方2.1开发的项目,部署完成后就可以开发华炎魔方项目了。

搭建开发环境

安装开发工具

Github 客户端

Mongodb 数据库图形化管理工具 Robo 3T

代码编辑工具 Visual Studio Code

安装运行环境

安装node

从官网下载我们推荐安装的12版的最后一个版本 12.22.10,请点击下载后安装。

更多版本请参考 https://nodejs.org/en/download/releases/ ,其他版本我们未充分测试过,如果需要使用其他版本请参阅Node.js长期维护版本日程 https://nodejs.org/zh-cn/about/releases/ 避免安装奇数版本。

安装yarn

nodejs安装完成之后打开终端执行以下命令安装yarn:

npm install -g yarn

安装Steedos Cli

安装或更新Steedos CLI命令工具

npm i steedos-cli --global

国内用户配置淘宝 NPM 镜像以提高 NPM 包下载速度:

npm config set registry https://registry.npm.taobao.org
yarn config set registry https://registry.npm.taobao.org

安装Mongodb数据库服务

参考官方安装文档安装数据库,建议安装4.2及以上版本

安装成功后需要修改配置文件以集群方式重启服务

Intel内核配置文件地址:

/usr/local/etc/mongod.conf

Apple M1内核配置文件地址:

/opt/homebrew/etc/mongod.conf

编辑配置文件(以M1内核配置文件为例):

vim /opt/homebrew/etc/mongod.conf
# 找到replication,去掉#并添加一行配置,没有replication则手动添加
replication: 
  # 以下配置必须缩进两个空格
  replSetName: rs0

保存后重启mongo服务生效

brew services restart mongodb-community@4.2

数据库初始化

# 首先进入mongo控制台
mongo
# 执行初始化函数
rs.initiate();
# 查看配置
rs.conf();
# 查看集群状态,确保members里有一个primary,则表示配置成功
rs.status();

安装Redis服务

参考官方文档安装,建议安装稳定版

源码编译安装:

# 解压下载的安装包
tar -zxvf redis-6.2.4.tar.gz
# 移动到指定的目录
mv -r redis-6.2.4 /usr/local
# 编译检测
make test
# 编译安装
make install

brew安装:

# 查找redis包
brew search redis
# 安装指定版本redis
brew install redis@4.0
# 安装完成后按照提示添加环境变量

启用redis服务:

redis-server

请注意,Redis安装完成后,需要在redis配置文件中补上以下配置,以防止启动项目时Redis报错:Redis-sub client is disconnected.

client-output-buffer-limit normal 0 0 0
client-output-buffer-limit replica 0 0 0
client-output-buffer-limit pubsub 0 0 0
client-output-buffer-limit slave 0 0 0

安装华炎魔方

创建项目

通过在终端执行 npx create-steedos-app my-app 命令创建 my-app 项目。

执行上述命令后会在当前文档夹下创建一个名为”my-app”的文件夹,其目录主要结构为:

my-app
├── .steedos
├── .vscode
├── jsreport-app
├── services
├── steedos-app
├── steedos-packages
├── .env
├── .env.local
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── Dockerfile-codeserver
├── index.js
├── lerna.json
├── moleculer.config.js
├── package.json
├── README.md
├── steedos-config.yml
└── yarn.lock

其中

  • .steedos: 引用第三方软件包的配置文件。
  • jsreport-app: 是一个独立的JsReport项目,用于设计各种报表。详情请参考 JsReport报表开发向导
  • steedos-app: 用于保存项目元数据和源码,华炎魔方启动是会自动加载其中的元数据。使用华炎魔方 DX 工具同步元数据时,默认同步到此文件夹中。
  • steedos-packages: 当你的项目需要分包管理时,可以使用此文件夹。你也可以把第三方软件包复制到此文件夹中,华炎魔方启动时会自动加载其中的元数据。
  • services: 用于保存微服务相关配置文件。
  • moleculer.config.js: 使用moleculer运行服务时的配置文件。
  • .env: 环境变量配置文件,可以配置端口、URL 等环境变量。
  • .env.local: 可以手工创建此文件,用于保存本地开发环境的配置。此文件不会上传到 GitHub 中。
  • steedos-config.yml: 华炎魔方配置文件,具体参考官方文档
  • package.json: 用于配置本项目依赖的 npm 包。如果需要升级 steedos 内核版本,也是修改此文件。

安装依赖包

使用vs code 打开解压后的文件夹,点击“终端”,打开命令窗口安装项目依赖的包

yarn

配置环境变量

如果您安装的版本较低,需要拷贝.env 到 .env.local,用于配置运行的服务的环境变量,指定MongoDB地址、Redis服务地址和ROOT_URL:

PORT=3000
ROOT_URL=http://localhost:3000
MONGO_URL=mongodb://localhost:27017/steedos
TRANSPORTER=redis://127.0.0.1:6379
CACHER=redis://127.0.0.1/1
STEEDOS_CLOUD_SPACE_ID=#在此填入私有部署记录中的魔方ID
STEEDOS_CLOUD_API_KEY=#在此填入私有部署记录中的API Key

请先 开通华炎魔方云服务 然后 激活华炎魔方,环境变量STEEDOS_CLOUD_SPACE_IDSTEEDOS_CLOUD_API_KEY的值就是其中新建的私有部署记录中的”魔方ID”和”ApiKey”。

请注意,最新版本的华炎魔方需要把ROOT_URL配置为像下面这种本地IP地址或外网域名才能被其他电脑正常访问,否则在列表视图界面会显示“未找到符合查询条件的集合”这种空列表。

ROOT_URL=http://192.168.0.95:3000

启动服务

执行命令启用服务

yarn start

待服务启动完成后,会自动使用默认浏览器打开地址  http://localhost:3000

升级内核版本

根目录下有一个package.json文件,该文件中可以维护项目中各个依赖的npm包的版本号。

要升级华炎魔方的内核版本号,只需要把该文件dependencies节点下的内容替换成 "@steedos/service-community": "^2.x" 或者 "@steedos/service-community": "指定版本" 就可以了。

{
  "dependencies": {
    "@steedos/service-charts": "2.1.27",
    "@steedos/service-metadata-server": "2.1.27",
    "@steedos/service-mongodb-server": "2.1.27",
    "@steedos/service-package-loader": "2.1.27",
    "@steedos/service-package-registry": "2.1.27",
    "@steedos/service-pages": "2.1.27",
    "@steedos/service-steedos-server": "2.1.27",
    ...
  }
}
  • 升级到最新版本

    "dependencies": {
         "@steedos/service-community": "^2.1"
    },
    
  • 升级到指定版本

    "dependencies": {
         "@steedos/service-community": "2.1.74"
    },
    

对于较老版本的魔方项目,在升级内核版本时,除了应该把版本号升级到最新的魔方版本之外,还需要确定下项目根目录下的steedos-config.yml,.env,package.json等文件与最新版本的 模板项目中同名文件内容是否有明显差异,推荐升级时把有差异的文件内容也复制到您的项目中以避免因配置文件不一致或缺少相关依赖包引起的问题。

修改好package.json文件中的版本号后,命令行中cd到项目目录并执行下yarn即可安装相关依赖包,待安装完成后再执行下yarn start即可以新版本启动服务。

:::info 查询最新steedos-server 版本号

:::

激活华炎魔方

华炎魔方私有部署版完全免费,可以参考以下教程为私有部署的华炎魔方配置华炎云账户,通过华炎云激活后,可解锁所有功能限制,并支持从应用市场下载和安装软件包,或是开发、发布自己的软件包。

请注意,激活过程中会自动为本地华炎魔方项目创建管理员账户,管理员用户名为手机号,初始密码为华炎云管理控制台中配置的默认密码。

如何激活华炎魔方 >

常见问题解答

本地项目运行后,登录的用户名密码是什么?

需要先激活华炎魔方,激活时新建华炎魔方会要求设置初始密码,成功激活后,本地华炎魔方项目就自动创建好了管理员账户,管理员用户名为手机号,初始密码为华炎云管理控制台中配置的默认密码。

激活过华炎魔方后是否可以断网运行?

只有华炎魔方的安装和激活过程要求连网,后续可以断网运行,不过付费软件包到期后需要重新续费激活。

mac mongodb开启账户验证

安装MongoDB服务后,系统默认不会开启账户验证,建议开启账户验证,提高服务的安全性。

首先,打开系统终端窗口,执行以下操作:

# 连上数据库
mongo;

# 切换到admin
use admin;

# 创建管理员账号
db.createUser({user: "adminUsername", pwd: "adminPassword", roles: [ { role: "userAdminAnyDatabase", db: "admin" } ] } );

# 切换到steedos
use steedos;

# 创建普通用户
db.createUser({user: "userUsername", pwd: "userPassword", roles: [ { role: "readWrite", db: "steedos" }, { role: "read", db: "local"} ] } );

# 切换到admin查看已创建的用户
use admin;
db.system.users.find().pretty();

# 退出数据库
exit;

编辑数据库配置文件mongod.conf,执行以下操作:

# 找到security,去掉'#'并新加一行
security:
  # 缩进两个空格
  authorization: enabled

保存修改后,执行命令重启数据库服务。

brew services restart mongodb-community@4.2 

修改华炎魔方项目的配置文件.env.local,添加mongo账户认证信息:

PORT=3000
ROOT_URL=http://localhost:3000
# 修改MONGO_URLMONGO_OPLOG_URL
MONGO_URL=mongodb://userUsername:userPassword@mongo:27017/steedos?replicaSet=rs0
MONGO_OPLOG_URL=mongodb://userUsername:userPassword@mongo:27017/local?replicaSet=rs0&authSource=steedos
MONGOMS_DOWNLOAD_MIRROR=https://www-steedos-com.oss-cn-beijing.aliyuncs.com/steedos/platform/bin/mongodb
MONGOMS_DEBUG=true
TRANSPORTER=redis://localhost:6379
CACHER=redis://localhost/1

保存配置文件,并重启华炎魔方项目。

\