# @cardstack/hub 中文文档

规范地址：https://npmcn.com/package/%40cardstack/hub/

版本：0\.28\.7
npm 元数据更新时间：2026-04-17T13:44:03.886Z
中文译文更新时间：2026-11-09T09:49:40.758Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cardstack/hub
原文对照：https://npmcn.com/package/%40cardstack/hub/?lang=original
项目主页：https://github.com/cardstack/cardstack#readme
源码仓库：https://github.com/cardstack/cardstack

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：131 MB，1770 个文件
- TypeScript 类型：未声明
- Node.js 要求：^14\.0
- 运行依赖：72 个
- 首次发布：2017-03-29T02:19:27.938Z
- 最新版本发布：2021-12-23T20:31:26.215Z
- 近 30 天下载量：3027（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：429（近 12 个月 0 个）

## 中文简介

卡斯特克技术堆栈的股票API服务器.

## 安装

```sh
npm install @cardstack/hub
```

也可以使用：`pnpm add @cardstack/hub`、`yarn add @cardstack/hub`、`bun add @cardstack/hub`

## README

# @ cardstack/ hub (中文(简体) )

卡斯特克枢纽是卡斯特克项目的API服务器. 更多信息,请参见 [整个项目](https://github.com/cardstack/cardstack/blob/main/README.md)。 。 。 .

-   [@ cardstack/ hub (中文(简体) )](https://npmcn.com/package/%40cardstack/hub/#readme-cardstackhub)
    -   [建筑](https://npmcn.com/package/%40cardstack/hub/#readme-architecture)
    -   [配置](https://npmcn.com/package/%40cardstack/hub/#readme-configuration)
    -   [设置 Discord](https://npmcn.com/package/%40cardstack/hub/#readme-setting-up-discord)
    -   [开始](https://npmcn.com/package/%40cardstack/hub/#readme-getting-started)
        -   [运行中枢](https://npmcn.com/package/%40cardstack/hub/#readme-running-the-hub)
    -   [数据库迁移](https://npmcn.com/package/%40cardstack/hub/#readme-database-migrations)
    -   [应用程序控制台](https://npmcn.com/package/%40cardstack/hub/#readme-application-console)
        -   [进行 DB 查询( 已安装的调用模块)](https://npmcn.com/package/%40cardstack/hub/#readme-make-a-db-query-call-installed-modules)
        -   [调用服务( 调用应用程序模块)](https://npmcn.com/package/%40cardstack/hub/#readme-call-a-service-call-application-modules)
    -   [在 AWS 上连接数据库中 {} 生产数据库](https://npmcn.com/package/%40cardstack/hub/#readme-connecting-to-the-database-stagingproduction-database-on-aws)
        -   [设置 AWS 会话管理器 ssh 配置](https://npmcn.com/package/%40cardstack/hub/#readme-setup-aws-session-manager-ssh-config)
    -   [提供 APIs](https://npmcn.com/package/%40cardstack/hub/#readme-provided-apis)
        -   [获取/api/汇率](https://npmcn.com/package/%40cardstack/hub/#readme-get-apiexchange-rates)
        -   [获得/api/预付卡片](https://npmcn.com/package/%40cardstack/hub/#readme-get-apiprepaid-card-patterns)
        -   [获取/api/预付卡-彩色方案](https://npmcn.com/package/%40cardstack/hub/#readme-get-apiprepaid-card-color-schemes)
        -   [POST/API/预付卡-定制](https://npmcn.com/package/%40cardstack/hub/#readme-post-apiprepaid-card-customizations)
        -   [POST / api/ 商家信息](https://npmcn.com/package/%40cardstack/hub/#readme-post-apimerchant-infos)
        -   [获取/api/ merchant- infos/ validate- slug/: slug 获取/ api/ merchant- infos](https://npmcn.com/package/%40cardstack/hub/#readme-get-apimerchant-infosvalidate-slugslug)
    -   [" 中心 " 倡议](https://npmcn.com/package/%40cardstack/hub/#readme-the-hub-cli)
    -   [卡片编译器](https://npmcn.com/package/%40cardstack/hub/#readme-the-card-compiler)
    -   [捐款](https://npmcn.com/package/%40cardstack/hub/#readme-contributing)

## 建筑

枢纽由API端点和邮递数据库组成.

该应用程序使用基于 Postgresql 的背景任务队列 [图表/工人](https://github.com/graphile/worker)

## 配置

以下列出枢纽接受的最常见环境变量列表:

-   `SERVER_SECRET` (需要) - 为您的机器生成一个,运行 `node --eval="console.log(crypto.randomBytes(32).toString('base64'))"`
-   `FIXER_API_KEY` (需为 `/api/exchange-rates`) - 货币汇率的API键,我们使用 [https://fixer.io/ 页面存档备份,存于互联网档案馆](https://fixer.io/)
-   `EXCHANGE_RATES_ALLOWED_DOMAINS` - 请求的域 `/api/exchange-rates` 允许
-   `HUB_AWS_ACCESS_KEY_ID`
-   `HUB_AWS_SECRET_ACCESS_KEY`
-   `HUB_AWS_REGION`
-   `AWS_PROFILE` - 如果没有HUB_自动取款机_\* 变量被定义,不会将证书或区域传递给aws-sdk. 这将让 aws- sdk 的默认行为生效, 包括使用 AWS PROFILE env var 如果设置它
-   `DATABASE_URL` - 开发中默认为postgres://postgres:postgres@localhost:5432/hub development
-   `LOG_LEVELS` - 默认 `*=info`

搜索单重播 `process.env` 并检查配置目录以查看引用的变量.

要使用变量,请创建名为的文件 `.env` ,并输入您想要使用的变量.

例如:

```
SERVER_SECRET=7TmgY1xFo/WrYTnAFSvAemZtFB8wQVMd8IkoeQKBboE=
AWS_PROFILE=cardstack
```

## 设置 Discord

这个单回波中的一些软件包支持一个不相通的bot的操作,它使用枢机的DI系统. 我们利用 [科德杰斯语Name](https://cordejs.org/docs/cordebot/) 我们的单位测试。 CordeJS使用不相容的bot在不相容下运行来测试bot的功能,方法是模仿不相容的用户,向被测试的bot发送命令. 为了运行cordejs测试,您需要设置一个不相容服务器,并安装拥有全部权限的cordebot以及cardbot进入不相容服务器.

设置接线人(和接线人)的指示在这里: [https://cordejs.org/docs/createddiscordbot (中文(简体) )](https://cordejs.org/docs/creatingdiscordbot)。在这些指令中,您需要设置 2 bots (指令概述了如何设置单个 bot) 。 一个你设置的机器人将是"纸牌",另一个你设置的机器人是"绳子"(用来测试纸牌).

在编写本报告时,纸牌机器人需要下列OAuth范围: ![](https://user-images.githubusercontent.com/61075/141373061-f16ffc2c-7139-4572-8c75-5eba75a0d47c.png)

一旦布置出卡片机器人和接线机器人bots,您就可以配置环境变量来进行机器人测试。 具体而言:

-   `CORDE_BOT_ID`: 绳子机器人的机器人ID
-   `CORDE_BOT_TOKEN`: 接线机器人的机器人标志
-   `CARDBOT_ID`: 纸牌机器人的机器人ID
-   `CARDBOT_TOKEN`: 纸牌机器人的机器人标志
-   `CARDBOT_ALLOWED_GUILDS`:一个逗号分隔列表,列出允许卡片机器人在其中通信的不和服务器ID. 这应该是您添加的纸牌机器人的服务器 .
-   `CARDBOT_ALLOWED_CHANNELS`:一个逗号分隔的频道ID列表,卡片机器人被允许进行通信.

(注:方便获得服务器和频道ID的启用) `User Settings -> Advanced -> Enable Developer Mode` 在迪斯科尔。 这将在服务器和频道的设置面板中显示一个"Copy ID"项目以获取这些ID. )

## 开始

你需要通过 `yarn build`,或者开始观看现场重建 `yarn rebuild`。 。 。 .

以下命令将在您本地运行的 postgres 服务器上创建中心开发数据库

```sh
    createdb hub_development
    yarn db:migrate up
    dist/hub.js db seed
    dist/hub.js db dump
    NODE_ENV=test dist/hub.js db init
```

### 运行中枢

```sh
# Starts the server on port 3000
dist/hub.js server

# Starts the worker process
dist/hub.js worker

# Starts the discord bot
dist/hub.js bot

# If you want to run both in the same terminal you can run
yarn start
```

## 数据库迁移

```sh
# Run available migrations
yarn db:migrate up

#To reverse the last migration:
yarn db:migrate down

#To redo the last migration (i.e. down + up):
yarn db:migrate redo

## Creating database migrations
yarn db:migrate create <migration-name>`
```

关于如何创建移徙脚本的文件,可查阅https://salsita.github.io/node-pg-migrate/#/migrates

在您完成运行新的 DB 迁移脚本后, 在 `config/structure.sql` 使用 :

```
dist/hub.js db dump
```

## 应用程序控制台

要在其上下文中测试,调试和调用应用程序的孤立部分.

`yarn console` 启动应用程序控制台.

实例:

### 进行 DB 查询( 已安装的调用模块)

```js
Hub > const { Client } = require('pg');
Hub > const config = require('config');
Hub > const client = new Client(config.db.url);
Hub > await client.connect();
Hub > await client.query('SELECT * FROM merchant_infos');
```

### 调用服务( 调用应用程序模块)

```js
Hub > const workerClient = await container.lookup('worker-client');
Hub > await workerClient.addJob('persist-off-chain-merchant-info', { id: 1 });
```

## 在 AWS 上连接数据库中 {} 生产数据库

### 设置 AWS 会话管理器 ssh 配置

在您的 `~/.ssh/config` 文件 :

```
# SSH over Session Manager
host i-* mi-*
    ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"
```

查找隧道指令和数据库密码 :

```
cd [PROJECTS]/cardstack/infra/configs/hub/[staging|production]
AWS_PROFILE=cardstack terraform output | grep tunnel_to_database
AWS_PROFILE=cardstack terraform output | grep postgres_password
```

运行命令, 打开一个 postgres 客户端, 并连接到本地主机, 端口 55432 , 并使用用户名 Cardtack, 密码 .

## 提供 APIs

API 符合 [JSON API 规格](https://jsonapi.org/)。 。 。 .

### 获取/api/汇率

### 获得/api/预付卡片

### 获取/api/预付卡-彩色方案

### POST/API/预付卡-定制

### POST / api/ 商家信息

### 获取/api/ merchant- infos/ validate- slug/: slug 获取/ api/ merchant- infos

## " 中心 " 倡议

可在中心软件包内引用中心语言

```
dist/hub.js
```

_QQ 提示: 添加 `export PATH="./bin:$PATH"` 给您的 `.zshenv` 或者说 `.bash_profile` 应援引 `hub` 直接(无 `bin/`(中文(简体) )_

支持 CLI 的文件在 `cli/` 目录。 你可以自己加一个 [根据这些指示](https://github.com/yargs/yargs/blob/master/docs/advanced.md#commanddirdirectory-opts)全数 `yargs` api 密码 [此处可见](https://github.com/yargs/yargs/blob/master/docs/api.md)。 。 。 .

## 卡片编译器

所有编译器功能目前都隐藏在COMPILER特性旗后. 所以用卡片编译和相关的路线开始服务器,使用那面旗.

```
COMPILER=true dist/hub.js server
```

## 捐款

注意此软件包是用 TypeScript 写的, 所以请确定运行类型Script 工作时编译器 . 见 [整个项目](https://github.com/cardstack/cardstack/blob/main/README.md) 用于了解当地运行枢纽及其测试的信息.

## 常见问题

### @cardstack/hub 是什么？

卡斯特克技术堆栈的股票API服务器\.

### 如何安装 @cardstack/hub？

在项目目录运行 npm install @cardstack/hub，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cardstack-hub，可以用 npx cardstack-hub 直接运行。

### @cardstack/hub 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cardstack\_\_hub 是否存在。

### @cardstack/hub 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^14\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cardstack/hub 可以商用吗？

@cardstack/hub 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cardstack/hub 的下载量有多少？

根据 npm 官方下载统计，@cardstack/hub 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,027 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cardstack/hub 还在维护吗？

最新版本 0\.28\.7 发布于 2021/12/24（4 年前）；至今共发布 429 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/03/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。