Skip to content

Commit

Permalink
更新文档
Browse files Browse the repository at this point in the history
  • Loading branch information
muxiangqiu authored Sep 22, 2024
1 parent 3072214 commit 269e396
Show file tree
Hide file tree
Showing 103 changed files with 1,331 additions and 1,331 deletions.
16 changes: 8 additions & 8 deletions .umirc.ts
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
import { defineConfig } from 'dumi';

export default defineConfig({
title: 'Malagu',
title: 'Cell',
mode: 'site',
// hash: true,
// more config: https://d.umijs.org/config
favicon: 'favicon.ico',

// locales: [['zh-CN', '中文'], ['en-US', 'English'] ],
locales: [['zh-CN', '中文']],
logo: 'https://cellbang-lib.oss-cn-hangzhou.aliyuncs.com/Malagu%20Logo%20Green.svg',
logo: 'https://cellbang-lib.oss-cn-hangzhou.aliyuncs.com/Cell%20Logo%20Green.svg',

menus: {
// 需要自定义侧边菜单的路径,没有配置的路径还是会使用自动生成的配置
Expand Down Expand Up @@ -98,7 +98,7 @@ export default defineConfig({
]
},
{
title: 'Malagu Blog 项目',
title: 'Cell Blog 项目',
children: [
'learn/blog-intro.md',
'learn/blog-create-project.md',
Expand Down Expand Up @@ -139,23 +139,23 @@ export default defineConfig({
// path: '链接是可选的',
// 可通过如下形式嵌套二级导航菜单,目前暂不支持更多层级嵌套:
children: [
{ title: '学习 Malagu', path: '/learn' },
{ title: '学习 Cell', path: '/learn' },
{ title: 'Vite 适配', path: '/learn/vite-intro'},
{ title: 'Package 文档', path: '/package' },
{ title: '参与贡献', path: '/malagu' },
{ title: '参与贡献', path: '/cell' },
],
},
// {
// title: '更多文档',
// path: 'https://www.yuque.com/cellbang/malagu',
// path: 'https://www.yuque.com/cellbang/cell',
// },
{
title: 'API 参考',
path: 'https://cellbang.github.io/malagu/docs/next/',
path: 'https://cellbang.github.io/cell/docs/next/',
},
{
title: 'GitHub',
path: 'https://github.com/cellbang/malagu',
path: 'https://github.com/cellbang/cell',
},
],

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Malagu Framework 文档
# Cell Framework 文档

本项目为 Malagu Framework 文档项目,欢迎大家一起共建。
本项目为 Cell Framework 文档项目,欢迎大家一起共建。

## 交流群

Expand Down
20 changes: 10 additions & 10 deletions docs/cloud/AWS Lambda.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc: menu

# AWS Lambda

我们可以使用 `@malagu/lambda-adapter``@malagu/lambda-plugin` 组件把应用部署到 aws lambda 平台,其中 `@malagu/lambda-adapter` 适配平台运行时接口,比如函数入口;`@malagu/lambda-plugin` 负责适配平台部署接口。基于约定大于配置原则,零配置,开箱即用。
我们可以使用 `@celljs/lambda-adapter``@celljs/lambda-plugin` 组件把应用部署到 aws lambda 平台,其中 `@celljs/lambda-adapter` 适配平台运行时接口,比如函数入口;`@celljs/lambda-plugin` 负责适配平台部署接口。基于约定大于配置原则,零配置,开箱即用。


## 云资源
Expand All @@ -21,7 +21,7 @@ toc: menu
## 环境隔离


Malagu 框架中,提供了一个顶级配置属性 `stage` 表示环境。而在 `@malagu/lambda-plugin` 组件约定的部署规则中,使用 `mode` 属性映射 `stage` 属性。默认提供了三套环境:测试、预发和生产。表达式规则如下:
Cell 框架中,提供了一个顶级配置属性 `stage` 表示环境。而在 `@celljs/lambda-plugin` 组件约定的部署规则中,使用 `mode` 属性映射 `stage` 属性。默认提供了三套环境:测试、预发和生产。表达式规则如下:
```yaml
stage: "${'test' in mode ? 'test' : 'pre' in mode ? 'pre' : 'prod' in mode ? 'prod' : cliContext.prod ? 'prod' : 'test'}" # test, pre, prod
```
Expand All @@ -36,13 +36,13 @@ stage: "${'test' in mode ? 'test' : 'pre' in mode ? 'pre' : 'prod' in mode ? 'pr
通过指定特殊的 `mode` 表示不同的部署环境:
```bash
# 部署到测试环境
malagu deploy -m test # 或者 malagu deploy
cell deploy -m test # 或者 cell deploy
# 部署到预发环境,我们也可以直接跳过预发环境的部署,直接部署到生产环境
malagu deploy -m pre
cell deploy -m pre
# 部署到生成环境
malagu deploy -m prod
cell deploy -m prod
```


Expand All @@ -54,14 +54,14 @@ malagu deploy -m prod

`stage` 属性值与函数别名关联(以下是默认规则,无需配置):
```yaml
malagu:
cell:
cloud:
alias:
name: ${stage}
```
API 网关的 `stage` 关联(以下是默认规则,无需配置):
```yaml
malagu:
cell:
cloud:
apiGateway:
stage:
Expand Down Expand Up @@ -90,11 +90,11 @@ mode:
#### 默认规则


默认规则定义在 `@malagu/lambda-plugin` 组件的 `malagu-*.yml` 配置文件中。
默认规则定义在 `@celljs/lambda-plugin` 组件的 `cell-*.yml` 配置文件中。

#### 自定义部署模式
```yaml
malagu:
cell:
mode:
- api-gateway # 默认值是 api-gateway,目前支持 api-gateway、timer
```
Expand All @@ -104,7 +104,7 @@ malagu:

#### 自定义函数名
```yaml
malagu:
cell:
cloud:
function:
name: xxxx # 默认值是 ${pkg.name}
Expand Down
10 changes: 5 additions & 5 deletions docs/cloud/Vercel 平台.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ toc: menu

# Vercel 平台

[Vercel](https://vercel.com/) 是国外一个用户体验很棒的 Serverless 平台。我们可以使用 `@malagu/vercel-adapter` 组件把应用部署到 Vercel 平台。基于约定大于配置原则,零配置,开箱即用。适配器组件基于 Vercel CLI 工具实现部署,所有部署的体验与该工具是一样的,甚至部署规则也是简单适配该工具的配置,只是采用了框架的配置文件方式。
[Vercel](https://vercel.com/) 是国外一个用户体验很棒的 Serverless 平台。我们可以使用 `@celljs/vercel-adapter` 组件把应用部署到 Vercel 平台。基于约定大于配置原则,零配置,开箱即用。适配器组件基于 Vercel CLI 工具实现部署,所有部署的体验与该工具是一样的,甚至部署规则也是简单适配该工具的配置,只是采用了框架的配置文件方式。


#### 云资源
Expand All @@ -18,15 +18,15 @@ toc: menu
#### 部署规则


我们可以通过同名覆盖自定义部署规则。默认规则定义在 `@malagu/vercel-adapter` 组件的 `malagu-remote.yml` 配置文件中。部署规则的配置项与 Vercel CLI 工具的配置文件 [`vercel.json`](https://vercel.com/docs/configuration) 是相同的。默认配置如下:
我们可以通过同名覆盖自定义部署规则。默认规则定义在 `@celljs/vercel-adapter` 组件的 `cell-remote.yml` 配置文件中。部署规则的配置项与 Vercel CLI 工具的配置文件 [`vercel.json`](https://vercel.com/docs/configuration) 是相同的。默认配置如下:
```yaml
malagu:
cell:
vercel:
config:
version: 2

frontend:
malagu:
cell:
vercel:
config:
builds:
Expand All @@ -37,7 +37,7 @@ frontend:
dest: frontend/$1

backend:
malagu:
cell:
vercel:
config:
builds:
Expand Down
42 changes: 21 additions & 21 deletions docs/cloud/云平台适配.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,29 @@ toc: menu

# 云平台适配

Malagu 框架是平台无关的,可以部署在各种 Serverless 平台、传统服务器之上。Malagu 框架抽象了一套统一的后端接口,不同平台只需要适配统一的后端接口即可。一般一个平台对应着一个适配器组件(可以多个),使用不同平台的适配组件,适配并部署到不同的平台。**适配器组件屏蔽掉平台底层细节,让平台的学习成本几乎为零**。目前框架已经适配的平台:
Cell 框架是平台无关的,可以部署在各种 Serverless 平台、传统服务器之上。Cell 框架抽象了一套统一的后端接口,不同平台只需要适配统一的后端接口即可。一般一个平台对应着一个适配器组件(可以多个),使用不同平台的适配组件,适配并部署到不同的平台。**适配器组件屏蔽掉平台底层细节,让平台的学习成本几乎为零**。目前框架已经适配的平台:

- `express-adapter` [传统服务器](https://malagu.cellbang.com/cloud/%E4%BC%A0%E7%BB%9F%E6%9C%8D%E5%8A%A1%E5%99%A8)
- `scf-adapter``scf-plugin` [腾讯云函数](https://malagu.cellbang.com/cloud/%E8%85%BE%E8%AE%AF%E4%BA%91%E4%BA%91%E5%87%BD%E6%95%B0)
- `fc-adapter``fc-plugin` [阿里云函数计算](https://malagu.cellbang.com/cloud/%E9%98%BF%E9%87%8C%E4%BA%91%E5%87%BD%E6%95%B0%E8%AE%A1%E7%AE%97)
- `lambda-adapter``lambda-plugin` [AWS Lambda](https://malagu.cellbang.com/cloud/aws%20lambda)
- `vercel-adapter` [Vercel 平台](https://malagu.cellbang.com/cloud/vercel%20%E5%B9%B3%E5%8F%B0)
- `express-adapter` [传统服务器](https://cell.cellbang.com/cloud/%E4%BC%A0%E7%BB%9F%E6%9C%8D%E5%8A%A1%E5%99%A8)
- `scf-adapter``scf-plugin` [腾讯云函数](https://cell.cellbang.com/cloud/%E8%85%BE%E8%AE%AF%E4%BA%91%E4%BA%91%E5%87%BD%E6%95%B0)
- `fc-adapter``fc-plugin` [阿里云函数计算](https://cell.cellbang.com/cloud/%E9%98%BF%E9%87%8C%E4%BA%91%E5%87%BD%E6%95%B0%E8%AE%A1%E7%AE%97)
- `lambda-adapter``lambda-plugin` [AWS Lambda](https://cell.cellbang.com/cloud/aws%20lambda)
- `vercel-adapter` [Vercel 平台](https://cell.cellbang.com/cloud/vercel%20%E5%B9%B3%E5%8F%B0)



## 使用方法


首先,确定我们需要运行和部署的平台,选择合适的适配器组件添加到项目依赖中。比如 `@malagu/express``@malagu/fc-adapter``@malagu/fc-plugin``@malagu/scf-adapter``@malagu/scf-plugin``@malagu/lambda-adapter``@malagu/lambda-plugin``@malagu/vercel-adapter`Malagu 组件是一个普通的 npm 包,可以通过以下命令安装:
首先,确定我们需要运行和部署的平台,选择合适的适配器组件添加到项目依赖中。比如 `@celljs/express``@celljs/fc-adapter``@celljs/fc-plugin``@celljs/scf-adapter``@celljs/scf-plugin``@celljs/lambda-adapter``@celljs/lambda-plugin``@celljs/vercel-adapter`Cell 组件是一个普通的 npm 包,可以通过以下命令安装:
```bash
# 安装腾讯云函数计算适配器组件
yarn add @malagu/scf-adapter
yarn add -D @malagu/scf-plugin
yarn add @celljs/scf-adapter
yarn add -D @celljs/scf-plugin
# 或者
npm i @malagu/scf-adapter
npm i -D @malagu/scf-plugin
npm i @celljs/scf-adapter
npm i -D @celljs/scf-plugin
```
安装好后,默认不需要任何配置,我们也不必知道该组件与函数计算的底层细节。当我们使用 `malagu deploy` 命令进行部署的时候,该组件会按照约定的部署规则将我们的代码部署到对应的平台。
安装好后,默认不需要任何配置,我们也不必知道该组件与函数计算的底层细节。当我们使用 `cell deploy` 命令进行部署的时候,该组件会按照约定的部署规则将我们的代码部署到对应的平台。


对于腾讯云函数计算,约定的部署规则是创建的服务名为项目名称,函数名为项目的名称,别名为 test 等等。约定的部署规则可以通过组件之间的属性覆盖自定义。
Expand All @@ -40,14 +40,14 @@ npm i -D @malagu/scf-plugin
在框架的 2.0 版本中,我们手动安装适配平台的包,我们只需通过模式属性指定我们需要部署到什么平台,框架会自动全局安装相关的包,并且这些包全局共享,其他项目可以复用,避免重复下载。我们也无需担心全局共享的这些包版本升级的问题,框架会在正确的时机自动升级,并且不同版本的包可以共存,框架保证使用的包版本是正确的。

```bash
malagu deploy -m scf # 部署到腾讯云函数
malagu deploy -m fc # 部署到阿里云函数计算
malagu deploy -m lambda # 部署到亚马逊云 Lambda
malagu deploy -m vercel # 部署到 Vercel 平台
malagu build -m server # 构建部署到传统服务器产物
malagu config -m scf # 配置腾讯云账号信息
malagu config -m lambda # 配置亚马逊云账号信息
malagu config -m fc # 配置阿里云账号信息
cell deploy -m scf # 部署到腾讯云函数
cell deploy -m fc # 部署到阿里云函数计算
cell deploy -m lambda # 部署到亚马逊云 Lambda
cell deploy -m vercel # 部署到 Vercel 平台
cell build -m server # 构建部署到传统服务器产物
cell config -m scf # 配置腾讯云账号信息
cell config -m lambda # 配置亚马逊云账号信息
cell config -m fc # 配置阿里云账号信息
```


Expand All @@ -73,4 +73,4 @@ malagu config -m fc # 配置阿里云账号信息

## 平台部署插件

腾讯云函数的部署插件是 `@malagu/scf-plugin`;阿里云函数计算的部署插件是 `@malagu/fc-plugin`;AWS Lambda 的部署插件是 `@malagu/lambda-plugin`。部署插件主要应用部署相关逻辑。它不关心平台函数入口细节差异,它只负责将构建的代码部署到相应的平台。
腾讯云函数的部署插件是 `@celljs/scf-plugin`;阿里云函数计算的部署插件是 `@celljs/fc-plugin`;AWS Lambda 的部署插件是 `@celljs/lambda-plugin`。部署插件主要应用部署相关逻辑。它不关心平台函数入口细节差异,它只负责将构建的代码部署到相应的平台。
8 changes: 4 additions & 4 deletions docs/cloud/传统服务器.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,20 @@ toc: menu

# 传统服务器

如果我们想把应用部署在传统服务器上,我们可以选择 `@malagu/express-adapter` 组件。构建输出产物在 `.malagu/dist` 目录下,其中 `backend` 为后端构建目标输出目录; `frontend` 为前端构建目标输出目录。运行后端应用直接使用 `node` 命令即可:
如果我们想把应用部署在传统服务器上,我们可以选择 `@celljs/express-adapter` 组件。构建输出产物在 `.cell/dist` 目录下,其中 `backend` 为后端构建目标输出目录; `frontend` 为前端构建目标输出目录。运行后端应用直接使用 `node` 命令即可:
```bash
node .malagu/dist/backend/index.js
node .cell/dist/backend/index.js
```


如果是前后端一体化应用,需要在切到 `backend` 的上级目录 `dist`
```bash
cd .malagu/dist
cd .cell/dist
node backend/index.js
```
因为静态文件的根目录默认是:
```yaml
malagu:
cell:
serve-static:
root: frontend # 相对执行目录计算
```
18 changes: 9 additions & 9 deletions docs/cloud/平台账号配置.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,21 @@ toc: menu

## 平台账号配置方式

当我们需要把 Malagu 应用部署到不同的云厂商的时候,我们需要通过一些方式提供 AKSK 给框架,框架使用 AKSK 部署到对应的云计算平台。不同的云厂商,会有不同的适配器,但是在 AKSK 的配置上会尽可能保持统一。框架提供如下方式配置 AKSK:全局配置文件 < 项目根下的 < `.env` 文件 < 环境变量 < 组件属性配置文件。框架提供了一个 `malagu config` 命令方便我们快速配置全局配置文件。
当我们需要把 Cell 应用部署到不同的云厂商的时候,我们需要通过一些方式提供 AKSK 给框架,框架使用 AKSK 部署到对应的云计算平台。不同的云厂商,会有不同的适配器,但是在 AKSK 的配置上会尽可能保持统一。框架提供如下方式配置 AKSK:全局配置文件 < 项目根下的 < `.env` 文件 < 环境变量 < 组件属性配置文件。框架提供了一个 `cell config` 命令方便我们快速配置全局配置文件。


### 全局云账号配置文件


全局云账号配置文件,一般不需要我们手动创建。当我们在执行部署命令的时候,框架发现当前环境下没有配置 AKSK,命令行将主动提示我们需要输入 AKSK 相关的信息,输入完后,自动保存到全局配置文件中。全局配置文件位置为 `~/.malagu` ,不同云厂商分别对于着不同的目录。如下所示:
全局云账号配置文件,一般不需要我们手动创建。当我们在执行部署命令的时候,框架发现当前环境下没有配置 AKSK,命令行将主动提示我们需要输入 AKSK 相关的信息,输入完后,自动保存到全局配置文件中。全局配置文件位置为 `~/.cell` ,不同云厂商分别对于着不同的目录。如下所示:

- 阿里云: `~/.malagu/alibaba/profile.yml` 
- 腾讯云: `~/.malagu/tencent/profile.yml`
- AWS: `~/.malagu/aws/profile.yml`
- 阿里云: `~/.cell/alibaba/profile.yml` 
- 腾讯云: `~/.cell/tencent/profile.yml`
- AWS: `~/.cell/aws/profile.yml`



绝大部分情况下,我们无需手动去配置全局配置文件,Malagu 的命令行工具提供了一个命令 `malagu config` 方便我们配置, `malagu config` 会根据项目的依赖情况,自动选择合适的云平台配置文件进行配置。例如,项目中依赖了 `@malagu/fc-plugin` 模块,则自动配置为阿里云函数计算平台的账号信息。
绝大部分情况下,我们无需手动去配置全局配置文件,Cell 的命令行工具提供了一个命令 `cell config` 方便我们配置, `cell config` 会根据项目的依赖情况,自动选择合适的云平台配置文件进行配置。例如,项目中依赖了 `@celljs/fc-plugin` 模块,则自动配置为阿里云函数计算平台的账号信息。
### 项目下的 `.env` 文件


Expand Down Expand Up @@ -50,9 +50,9 @@ MALAGU_TOKEN=xxxxx
### 组件属性


Malagu 框架的组件属性是通过 `malagu-[mode].yml` 配置,配置方式如下:
Cell 框架的组件属性是通过 `cell-[mode].yml` 配置,配置方式如下:
```yaml
malagu:
cell:
cloud:
credentials:
accessKeyId: xxxxxx
Expand All @@ -77,7 +77,7 @@ malagu:
### 阿里云部署
当首次运行 malagu deploy 时需要配置**Account Id、Access Key Id、Access Key Secret**,
当首次运行 cell deploy 时需要配置**Account Id、Access Key Id、Access Key Secret**,
**
#### 如何获取AccessKey ID、AccessKey Secret、**Account Id?**
Expand Down
Loading

0 comments on commit 269e396

Please sign in to comment.