# @atlassian/atlassian-connect-express 中文文档

规范地址：https://npmcn.com/package/%40atlassian/atlassian-connect-express/

版本：12\.2\.3
npm 元数据更新时间：2026-05-01T00:59:49.784Z
中文译文更新时间：2026-11-07T03:07:30.149Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40atlassian/atlassian-connect-express
原文对照：https://npmcn.com/package/%40atlassian/atlassian-connect-express/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-connect-express
源码仓库：http://bitbucket.org/atlassian/atlassian-connect-express

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

- 包体积（解压后）：205 kB，37 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：17 个
- peer 依赖：express 3\.0 - 4
- 首次发布：2025-05-20T00:25:14.934Z
- 最新版本发布：2026-05-01T00:59:49.638Z
- 近 30 天下载量：17536（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 3 个）

## 中文简介

用于在快递站上建造Atlassian Add-on的图书馆

## 安装

```sh
npm install @atlassian/atlassian-connect-express
```

也可以使用：`pnpm add @atlassian/atlassian-connect-express`、`yarn add @atlassian/atlassian-connect-express`、`bun add @atlassian/atlassian-connect-express`

## README

# 地图集-连接-表达式: Express.js的节点.js包 基于 Atlassian Add-ons

## ưμ㼯A

**终止对Atlassian连接框架的支持**

Atlassian将与Atlassian连接平台同时停止对ACE框架的支持.

请看看这个 [博客文章](https://www.atlassian.com/blog/developer/announcing-connect-end-of-support-timeline-and-next-steps) 用于连接支持结束的详细时间表.

我们鼓励开发者社区在需要时叉出并维护这些储存库.

## 捷克

`atlassian-connect-express` (ACE)是一个用于创建 [阿特拉斯连接](https://developer.atlassian.com/display/AC/Atlassian+Connect) 基于加载 [节点.js](http://nodejs.org/). Atlassian Connect是用于创建加成的分布式组件模型. 与Atlassian Connect公司所建的加码,将Atlassian以云为基础的应用扩展至标准网络协议和API. 要为Atlassian的服务器(premises)产品建立加码,请参见: [服务器开发者文档](https://developer.atlassian.com/server/)。 。 。 .

ACE就是那个 **官方支持** Atlassian Connect的节点.js框架. 请阅读我们的文件,看看另一个 支助和社区 [框架和工具](https://developer.atlassian.com/static/connect/docs/latest/developing/frameworks-and-tools.html)。 。 。 . 在撰写自己的 Atlassian Connection 附加数据时, 您会发现推荐的工具非常有用; 请仔细浏览 工具清单,并尽可能将其用于援助发展.

**请确保您总是使用最新的补丁版ACE,以确保您的加载有最新的安全补丁和 修复。 1.0.14和2.0.2之前的版本存在已知的安全弱点.**

## 更多信息

ACE帮助您快速开始开发加载,将Node.js和Express作为加载服务器.

必须明白 [快递](http://expressjs.com/) 单是节点的网络应用框架。 ACE只是提供 一个中间软件和方便帮助器的图书馆,使Atlassian的加成更加容易。 具体而言,ACE补充说:

-   在启动和关闭时处理针对您的Atlassian应用程序的注册和注销,从而优化了dev循环.
-   检测更改到的文件系统监视器 `atlassian-connect.json`如果有的话。 当检测到变化时,加载会重新在主机注册.
-   JWT自动认证入境请求以及JWT为出境请求签名返回主机.
-   自动坚持主机细节(即客户端密钥,主机公钥,主机基础url等).

## 发布注释

关于详细的发行说明和升级指南,请参见 [发布注释](https://npmcn.com/package/%40atlassian/atlassian-connect-express/RELEASENOTES.md)。 。 。 .

## 开始

最快的启动方法是安装 `@atlassian/atlas-connect` CLI工具. CLI 可以生成ACE 快速启用加载脚手架 。 要安装 :

```bash
npm i -g @atlassian/atlas-connect
```

### 创建工程

我们先创建一个附加项目:

```bash
atlas-connect new <project_name>
```

这将在当前目录中创建一个新项目 .

### 安装依赖关系

更改为新项目目录 。 要绕过一些过时的过渡性依赖,在根上添加以下的覆盖 `package.json` 文件 :

```
  "overrides": {
    "form-data": "^4.0.4",
    "tough-cookie": "^4.1.3"
  }
```

然后安装依赖性 :

```bash
npm install
```

如果您得到与节点- gyp( 特别是Windows上的节点8) 相关的任何错误, 请尝试 [安装其先决条件](https://www.npmjs.com/package/node-gyp#installation)。 。 。 .

### 创造发展环境

此时,你们都准备运行附加程序,但是仍然需要安装在Jira或Confact. 您可以在任何您是管理员的 Jira 或 Convolution 主机中安装您的新添加, 但通常 最好为您创建一个新的主机,供您在开发期间使用. [跟着这个链接报名](http://go.atlassian.com/cloud-dev) 自由的吉拉或相会云宿主.

### 运行您的添加服务器

在您的工程目录中, 运行 :

```bash
npm start
```

这将启动您的 Express 服务器在默认的 3000 端口 .

### 开发环路

此时,你可以开始建造你的附加. 但是,如果修改到 任何 JavaScript, 您需要重新启动快递 。 如果您想要您的服务器在 JavaScript 时自动重新启动 更改,考虑使用 [节点恶魔](https://npmjs.org/package/nodemon) 或诸如来.

#### 自动登记

本节将描述如何配置 ACE , 这样它可以自动注册您的添加 Jira 或 Congublic host, 重新登记对描述符的更改, 并注销关闭的注册 .

注意自动注册需要在启动时显示一个描述文件.

要获得此功能, 您需要:

_生成一个 Atlassian API 令牌_

-   创建名为的文件 `credentials.json`, (中文(简体) ),
-   复制并粘贴 [此文件](https://bitbucket.org/atlassian/atlassian-connect-express-template/src/master/credentials.json.sample), (中文(简体) ),
-   添加 `credentials.json` 页:1 `.gitignore` 文档,以及
-   更改文件内容以包含与您的开发环境的链接, 电子邮件为用户名 , [API 令牌](https://confluence.atlassian.com/cloud/api-tokens-938839638.html) 作为密码和产品名称.

#### 公开显示您的附加( 打开您自己的地道)

-   截至第12版,ngrok地道不再自动创建.
-   如果您的 Atlassian 主机是远程的 (\*. atlassian.net), 您的加载必须可以公开获取 。 ACE不再创建或管理地道.
-   使用任何方法公开曝光您的本地服务(例如ngrok这样的地道提供商).
-   配置 ACE 通过配置 AC LOCAL BASE URL 或 localBaseUrl 来使用您的公共 URL

```bash
export AC_LOCAL_BASE_URL=https://your-public-url.example
```

ACE 在您开发主机上注册您的添加时, 将使用您配置的公共基址 URL .

### 配置

您添加的配置在两个文件中完成 :

-   `./config.json` - 说吧 此文件包含您插件运行的每个运行时环境的配置 。 文件已经 注释帮助您理解可用的设置.
-   `./atlassian-connect.json` - 说吧 此文件是您添加的所有扩展点的列表 。 要查看所有可供 Jira 使用的扩展点选项,请检查该选项的模块部分 [地图集连接的Jira模块文件](https://developer.atlassian.com/cloud/jira/platform/about-connect-modules-for-jira/)。要检查所有可用的“聚合”扩展点选项,请检查该模块的模块部分 [地图集连接的聚合模块文件](https://developer.atlassian.com/cloud/confluence/connect-modules/)。 。 。 .

通过设置 `AC_OPTS` 环境变量(见本节末尾).

#### 配置( json)

这个 `./config.json` 文件包含添加服务器的所有设置。 此文件被分解为环境 .

```javascript
{
  // This is the default environment. To change your app to use
  // a different env, set NODE_ENV (http://expressjs.com/api.html#app.configure)
  "development": {
    // Set to true if your app contains a errorHandler middleware:
    // https://expressjs.com/en/guide/error-handling.html
    "expressErrorHandling": false,

    // This is the port your Express server will listen on
    "port": 3000,

    // Use views/unauthorized.hbs for error page.
    "errorTemplate": true,
    // Use custom error template
    // "errorTemplateName": "auth-response-handler.jsx",
    
    // Use Custom error object for error template
    // "errorTemplateObject": {
    //     "title": "App not authorized!",
    //     "unauthorized": true
    // },

    // To enable validation of descriptor on startup and every time it changes,
    // add the optional config validateDescriptor to true
    "validateDescriptor": true,

    // atlassian-connect-express currently integrates with Sequelize for
    // persistence to store the host client information (i.e., client key,
    // host public key, etc). When no adapter is specified, it defaults to
    // Sequelize's fallback memory storage.
    //
    // To specify a backend for Sequelize  other than "memory", set the
    // "dialect" value to one of Sequelize's other supported dialects.
    //
    // To use your own storage adapter, add the key
    // "adapter" to the following configuration, and replace "dialect"
    // and "connection" with any values your adapter expects.  Then make sure
    // that you register your adapter factory with the following code in
    // app.js:
    //
    //   ac.store.register(adapterName, factoryFn)
    //
    // See `atlassian-connect-express/lib/store/index.js` and the default
    // `sequelize.js` files for code demonstrating how to write a
    // conformant adapter.  The default values are as follows:
    //
    //   "store": {
    //     "adapter": "sequelize",
    //     "dialect": "sqlite",
    //     "storage": ":memory:"
    //   },
    //
    //
    // To use sqlite with a persistent file instead of an in-memory database, the following settings can be used,
    // and will result in a store.db file being created in the working directory of the app:
    // 
    //   "store": {
    //     "adapter": "sequelize",
    //     "dialect": "sqlite3",
    //     "url": "sqlite://./store.db"
    //   },
    //
    // To instead configure, say, a PostgreSQL store, the following could be
    // used:
    //
    //   "store": {
    //     "adapter": "sequelize",
    //     "dialect": "postgres",
    //     "url": "postgres://localhost/my_addon_database",
    //     "table": "MySetting" //optional - table name. Default is "AddonSetting"
    //     "logging": function, //optional - function that gets executed every time Sequelize would log something.
    //     "pool": {}           //optional - pool options you have that you may pass to sequelize adapter
    //   },
    //
    // For MongoDB, use the following:
    //
    //   "store": {
    //     "adapter": "mongodb",
    //     "url": "mongodb://localhost:27017/my_addon_database",
    //     "collection": "AddonSettings"
    //   },
    //
    // For Redis, use the following:
    //
    //   "store": {
    //     "adapter": "redis",
    //     "url": "redis://localhost:6379",
    //   },    
    //
    // For DynamoDB, use the following:
    //
    //   "store": {
    //     "adapter": "dynamodb",
    //     "table": "AddonSettings",
    //     "region": "us-east-1",
    //   },
    //
    //  Note that the DynamoDB table should have "clientKey" as a string
    //  partition key and "key" as a string sort key.
    //
    // You will also need an appropriate Sequelize driver if you choose something
    // other than the default "dialect".  In the PostgreSQL case you'd need to
    // run the following command to add the proper support:
    //
    //   $ npm install --save pg
    //
    // You will also need aws-sdk if you choose the DynamoDB driver:
    //
    //   $ npm install --save @aws-sdk/client-dynamodb
    //

  },

  // This is the production add-on configuration, which is enabled by setting
  // the NODE_ENV=production environment variable.
  "production": {
    // On a PaaS host like Heroku, the runtime environment will provide the
    // HTTP port to you via the PORT environement variable, so we configure
    // that to be honored here.
    "port": "$PORT",
    // This is the public URL to your production add-on.
    "localBaseUrl": "https://your-subdomain.herokuapp.com",
    // This is the URL to atlassian connect all.js.
    "hostScriptUrl": "https://connect-cdn.atl-paas.net/all.js",
    "store": {
      // You won't want to use the memory store in production, or your install
      // registrations will be forgotten any time your app restarts.  Here
      // we tell atlassian-connect-express to use the PostgreSQL backend for the default
      // Sequelize adapter.
      "dialect": "postgres",
      // Again, a PaaS host like Heroku will probably provide the db connection
      // URL to you through the environment, so we tell atlassian-connect-express to use that value.
      "url": "$DATABASE_URL"
    },

    // If your app supports multiple baseUrls,
    // additional baseUrls can be added here so that it can be used to
    // verify the `audience` claim during installation lifecycle callback.
    "allowedBaseUrls" : [
      "https://other-domain.herokuapp.com"
    ],

    // Make sure that your add-on can only be registered by the hosts on
    // these domains.
    "whitelist": [
      "*.jira-dev.com",
      "*.atlassian.net",
      "*.jira.com"
    ]
  }
  
  // If your app is being used as a remote backend for Forge, this value will 
  // set the clock tolerance to use when verifying the `not before time` and 
  // `expiration time` claims in the invocation token.  The value is in seconds.
  // "clockTolerance": 0
}
```

#### AC OPTS (法语)

AC OPTS环境变量可用于改变ACE的行为以方便开发,比如:

```bash
AC_OPTS=no-auth,force-reg node app.js
```

设定为包含以下一个或多个值的被分隔的空格或逗号列表.

**军法** 让加载器在启动时以运行 Jira 或 Conculation 主机来注册 (通常自动注册只在加载使用存储器时才会发生). 此环境变量必须存在描述文件才能应用 .

**部队德格** 关闭时运行 Jira 或 Conclusive 主机, 使加码自动取消注册 (通常只有在加载使用内存存储或运行在开发模式下时才会自动注册). 此环境变量必须存在描述文件才能应用 .

**无记录** 运行 Jira 或 Congublishing 主机, 使加载永不注册 (即即使使用记忆存储器也不自动注册).

**无** 跳过收到的请求的认证(即不检查或验证JWT令牌).

### 地图集-连接.json

这个 `atlassian-connect.json` 描述你加的会做什么。 说明书有三个主要部分: 描述您添加的信息(即名称、描述、密钥等)、权限和认证信息, 并列出您添加的组件列表 。 此描述符被发送到主机( 即 Jira 或 Collection) 当您的加载安装时.

查看当前 `atlassian-connect.json`,访问 [地图集连接文件](https://developer.atlassian.com/static/connect/docs/)

如果您需要您描述符的预处理步骤, 您可以通过修改您的描述符来配置 `app.js` 使变压器包括在 `config`编辑 `descriptorTransformer` 属性预计为 函数和通过 `descriptor` 作为物体,以及 `app.config` 对象.

```javascript
var addon = ac(app, { config: {
  descriptorTransformer: function(descriptor, config) {
    if (config.environment() === "production") {
      descriptor.key = "production-key";
    }
    return descriptor;
  }
}});
```

### 没有描述符运行 ACE

ACE在以描述符启动您添加的服务器时,能够自动注册/删除您的应用程序与您的主机,并配置来自描述符的路由. 然而,在迁移到Forge时,您可能不再对描述文件有任何用途,因此可能想要在没有它的情况下运行ACE. 在这种情况下,必须意识到以下功能的变化:

-   ACE将不再自动注册您的附加, 重新注册描述符的更改, 并注销关闭时的注册 .
    -   这个 `AC_OPTS` 环境变量不会改变这种行为
-   ACE不再根据描述定义自动生成路径. 例如 `/installed` 使用寿命周期处理器或描述符中定义的任何webhook处理器将不再生成.
    -   如果您的添加需要这些, 您必须手动执行 .
    -   任何认证中间软件都可以通过配置 `localBaseUrl` 或者说 `allowedBaseUrls` 区域 `config.json`
-   这个 `createJwtPayload` 方法,作为 `HostClient` 类,如果不提供发件人作为参数,则默认使用附加键.
    -   此默认行为可以通过配置 `appKey` 输入 `config.json` 或经过 `AC_APP_KEY` 环境变量.

只要您继续使用任何连接模块,描述符就不应该被删除.

## 样本加载

-   [Jira 实例](https://bitbucket.org/atlassianlabs/atlassian-connect-jira-example) - 一个简单的Jira例加到
-   [组合示例](https://bitbucket.org/atlassianlabs/atlassian-connect-confluence-example) - 一个简单的聚合实例添加到

## 脚手架

当你生成新的 ACE 添加, 你实际上只是下载一个副本 [Express.js 模板的 Atlassian 连接](https://bitbucket.org/atlassian/atlassian-connect-express-template/)。 。 。 .

### 处理栏布局和模板

底部脚手架使用 [处理栏](http://handlebarsjs.com/) 通过该模板库 [速记](https://www.npmjs.com/package/express-hbs) 软件包.

手提栏视图存储于 `./views` 目录。 基准模板包含一个 `layout.hbs` 和样本页 (单位:千美元)`hello-world.hbs`) (中文(简体) ). 单靠手提棒并不能提供布局,但 `express-hbs` 软件包。 应用 `layout.hbs` 在模板页面上添加以下内容:

```hbs
{{!< layout}}
```

为了更深入地了解汉德勒巴斯如何用快活方式工作,请看看 [速成文件](https://www.npmjs.com/package/express-hbs)。 。 。 .

### 特殊上下文变量

ACE 在您的渲染上下文中注入了几个有用的上下文变量 。 您可以访问任意 在您的模板中列出:

-   `title`: 加号名称(取自 `atlassian-connect.json`(中文(简体) )
-   `addonKey`: 定义于 `atlassian-connect.json`
-   `localBaseUrl`: 加法的基 URI
-   `hostBaseUrl`: 目标应用程序的基础URI(如果有的话包括上下文路径)
-   `hostStylesheetUrl`:用于 Connect 加载的基础 CSS 文件的 URL. 此样式表是一个最小的样式集 帮助你开始。 这不是完整的 AUI 样式表 .
-   `hostScriptUrl`: 连接JS客户端的URL. 这份联合材料文件载有建立无缝密码 iframe 介于添加和其父之间。 它还载有一些获取数据的方法和对象 通过父( 查找 `AP` 联合来文反对).
-   `token`:可以用来验证从iframe返回到加载服务的来电的符.
-   `license`: 许可证状况
-   `context`: 西北地区 `context` 索赔
-   `clientKey`: 客户端消费密钥, 用于识别请求来自的 Jira 或 Congress 主机
-   `userAccountId`:用户的Atlassian账户ID.
-   `userId`: (被贬)请求来源的用户名.
-   `timeZone`: (贬值)用户的时区
-   `locale`: (贬值) 用户的地块

您可以将上面的任何变量作为普通的 Handlebar 变量访问 。 例如,在页面中创建链接 链接到主机其它位置的:

```html
<a href="{{hostBaseUrl}}/browse/JRA">Jira</a>
```

### 排放的事件

#### 所有产品

-   `host_settings_saved`: 之后 `/installed` 生命周期, ACE 试图保存存储中的客户端信息( baseUrl, 客户端Key, app key, puglinsVersion, 产品Type, publicKey, 服务器Version, shareSecret). 如果成功保存, 此事件会被释放
-   `host_settings_not_saved`: 之后 `/installed` 生命周期,ACE试图保存存储中的客户端信息. 如果有任何错误或问题,此事件会被发布
-   `addon_registered`: ACE试图在 Jira 或 Conference 产品中注册或安装应用程序后
-   `webhook_auth_verification_triggered`: ACE 一旦尝试认证此事件, 将自动在描述文件中注册 Webhooks 和相应的路径
-   `webhook_auth_verification_successful`: ACE 一旦尝试认证并成功, 将自动在描述文件中注册 Webhooks 和相应的路径

#### 吉拉/影响

-   `addon_deregistered`: 当ACE收到 `SIGTERM`, (中文(简体) ), `SIGINT`,以及 `SIGUSR2` 信号,它会解除应用程序的注册 并且这个事件已经发布

聆听一个事件:

```
addon.on(event, function() {
  // Add something here
});
```

## 食谱

### 如何与 JWT 保证线路的安全

加号通过JWT认证. 为了简化路线上的JWT验证,您只需添加一个 ACE 中间软件到您的路径 :

```javascript
module.exports = function(app, addon) {
  app.get(
    '/protected-resource',

    // Protect this resource with JWT
    addon.authenticate(),

    function(req, res) {
      res.render('protected');
    }
  );
};
```

仅仅添加 `addon.authenticate()` 中间软件将保护您的资源.

### 如何用 JWT 保护安装回调线路

通过不对称JWT验证安装/Uninstall钩. 只需添加一个 捷克 `authenticateInstall` 自定义安装或卸载生命周期路径的中间软件 :

```javascript
module.exports = function(app, addon) {
  app.post(
    '/uninstalled',

    // Protect this install callback resource with asymmetric JWT
    addon.authenticateInstall(),

    function(req, res) {
      res.status(204).send();
    }
  );
};
```

如果你收养了Forge,请确保 `baseUrl` 在您描述文件中配置的文本与在所有环境中的显示中匹配 。 匹配错误的碱基Urls会导致中间软件内部的认证出错. 为尽量减少出现差异的风险,考虑使用 `config.json` 参数化文件 `localBaseUrl`。 。 。 .

#### 授权请求

如果您的app API 接受前端使用上下文 JWTs 的请求,则必须进行授权检查. Atlassian Connect Express中包含一个基本中间软件,它利用了 [Jira 获得批量权限 API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-permissions/#api-rest-api-3-permissions-check-post) 财务报告和审定财务报表 [组合检查内容权限 API](https://developer.atlassian.com/cloud/confluence/rest/api-group-content-permissions/#api-api-content-id-permission-check-post) 根据上下文JWT进行授权检查.

例如,将终点限制在同时也是项目管理员的Jira admins:

```javascript
module.exports = function(app, addon) {
  app.get(
    '/admin-resource',

    [
      addon.authenticate(true /* accept context JWTs */),
      // only allow product admins that are also project admins
      addon.authorizeJira({ global: ["ADMINISTER"], project: ["ADMINISTER_PROJECTS"] })
    ],

    function(req, res) {
      res.render('protected');
    }
  );
};
```

同样,对于 Conference , 将一个端点限制在 Conference 管理员上, 这些管理员也有读取当前页面的权限 :

```javascript
module.exports = function(app, addon) {
  app.get(
    '/admin-resource',

    [
      addon.authenticate(true /* accept context JWTs */),
      // only allow product admins that also have access to read the current page
      addon.authorizeConfluence({ application: ["administer"], content: "read" })
    ],

    function(req, res) {
      res.render('protected');
    }
  );
};
```

### 如何从 Iframe 发送签名的 HTTP 请求回加载服务

如上所述,装入iframe内容的初步呼叫由JWT保证。 然而,装入的内容不能 签名后续请求。 一个典型的例子是让AJAX调回加词的内容. Cookie 会话无法 由于许多浏览器默认会阻断第三方 cookie 。 ACE 提供中间软件 工作时不需要饼干 并且帮助从iframe 安全请求.

标准JWT标志用于认证从iframe返回加载服务的请求. 路径可以安全 使用 `addon.checkValidToken()` 中间软件 :

```javascript
module.exports = function(app, addon) {
  app.get(
    '/protected-resource',

    // Require a valid token to access this resource
    addon.checkValidToken(),

    function(req, res) {
      res.render('protected');
    }
  );
};
```

为了保障您的路由安全, 信使必须是 HTTP 请求的一部分 。 可以这样 使用标准 `jwt` 查询参数 :

```html
<a href="/protected-resource?jwt={{token}}">See more</a>
```

第二个选项是使用授权 HTTP 头, 例如用于 AJAX 请求 :

```javascript
beforeSend: function(request) {
  request.setRequestHeader("Authorization", "JWT {{token}}");
}
```

您可以使用 `token` 内容可变。 例如,你可以嵌入 它在一个元标记中,从其中它以后可以用脚本读取:

```html
<meta name="token" content="{{token}}">
```

### 如何向主机发送已签名的输出 HTTP 请求

ACE 捆绑并扩展 [请求](https://www.npmjs.com/package/request) HTTP客户端. 做一个 JWT 签名请求返回主机, 您只需使用 `request` ,但使用 URL 回 主持人的REST APIs.

```javascript
var httpClient = addon.httpClient(req);
httpClient.get('/', function(err, res, body) {
  ...
});
```

如果在请求上下文中没有,您可以按以下方式进行等同的操作:

```javascript
var httpClient = addon.httpClient({
  clientKey: clientKey  // The unique client key of the tenant to make a request to
});
httpClient.get('/', function(err, res, body) {
  ...
});
```

默认情况下,这些请求被认证为附加请求. 如果您想作为一个特定用户提出请求,则 `#asUserByAccountId()` 应使用方法。 在封面下,将为用户取取一个OAuth2无记名代号 你要求过.

```javascript
var httpClient = addon.httpClient(req);
httpClient.asUserByAccountId('ebcab857-c769-4fbd-8ad6-469510a43b87').get('/rest/api/latest/myself', function(err, res, body) {
  ...
});
```

确保您通过 `userAccountId` ,而不是用户名或用户Key。 如果你之前使用过 `#asUser()` 与 `userKey`,您可以通过主机产品上的用户 REST 资源将其转换为用户 AccountId .

-   [贾拉](https://developer.atlassian.com/cloud/jira/platform/rest/#api-api-2-user-get)
-   [组合](https://developer.atlassian.com/cloud/confluence/rest/#api-user-get)

也可以设置自定义标题或发送窗体数据。 例如,请将一个文件附于Jira问题:

```javascript
var filePath = path.join(__dirname, 'some.png');
fs.readFile(filePath, function(err, data) {
  httpClient.post({
    url: '/rest/api/2/issue/' + issueKey + '/attachments',
    headers: {
      'X-Atlassian-Token': 'nocheck'
    },
    multipartFormData: {
      file: [data, { filename: 'some.png' }]
    }
  },
  function(err, httpResponse, body) {
    if (err) {
      return console.error('Upload failed:', err);
    }
    console.log('Upload successful:', body);
  });
});
```

### 使用产品 REST API

某些 REST URL 可能需要 [其他范围](https://developer.atlassian.com/static/connect/docs/scopes/scopes.html) 应该添加到您的 `atlassian-connect.json` 文档.

## 福尔吉

您的 ACE 应用程序可以作为一个 [forge 的远程后端](https://developer.atlassian.com/platform/forge/forge-remote-overview/)。 。 。 .

要做到这一点,它必须有一个 `appId` 设置于 `./config.json`。数值应为: `app.id` 如在福尔吉号上所示 [显示](https://developer.atlassian.com/platform/forge/manifest-reference/)。例如:

```javascript
{
  "appId": "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"
}
```

或者,如果您的后端会支持多个应用程序,则可以提供列表:

```javascript
{
  "appId": [
    "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a",
    "ari:cloud:ecosystem::app/b7e2e2e2-3c4a-4b7a-9e2a-1f2b3c4d5e6f"
  ]
}
```

如果您使用 DynamoDB 适配器进行存储, 您还需要添加几个表格 用于 Forge 安装相关数据。 有代码试图创建这些表格 [这里](https://npmcn.com/lib/store/dynamodb.js#L31) 但如果您的应用程序不能成功 没有必要的许可。 在这种情况下,请手动创建如下:

-   一个 `InstallationClientKeys` 表格为 `installationId` 作为字符串分区键.
    
-   A 类 `ForgeSettings` 表格为 `installationId` 作为字符串分区键,以及 `key` 作为字符串排序键.
    

### 认证 Forge 的请求

这个 `addon.authenticateForge()` 中间软件将依照 [远程合同](https://developer.atlassian.com/platform/forge/forge-remote-overview/#remote-contract) 并设置以下属性: `request.context.forge`。 。 。 . 参见 [远程合同参考](https://developer.atlassian.com/platform/forge/forge-remote-overview/#remote-contract) 关于这些属性的更多信息.

-   `request.context.forge.tokens.app`: 代表应用程序的即时使用访问符
-   `request.context.forge.tokens.user`: 代表当前用户的即用访问令牌
-   `request.context.forge.apiBaseUrl`: API 基础 URL,所有产品 API 请求应当被路由. 示例 [https://api.atlassian.com/ex/coffec.822e2f-510f-48b9-b8d2-8419d0932949 页面存档备份,存于互联网档案馆](https://api.atlassian.com/ex/confluence/4c822e2f-510f-48b9-b8d2-8419d0932949)
-   `request.context.forge.app`: 关于应用程序和安装上下文的信息
-   `request.context.forge.context`: 产品和推广特定数据,包括配置.

### 向Atlassian APIs提出请求

ACE 框架允许您向 Atlassian API 提出请求。 请确保您的清单配置 以便你们获得所需的迹象 [此处详述](https://developer.atlassian.com/platform/forge/remote/calling-product-apis/)。 。 。 . 然后在处理Forge引用时使用ACE所曝光的Forge-aware HTTP客户端:

```javascript
app.get("/forge/backend/resource", addon.authenticateForge(), async (req, res) => {
  const http = addon.forgeHttpClientAsApp(req); // or forgeHttpClientAsUser(req)
  const data = await http.get({ url: "/wiki/api/content" });
  res.json(data);
});
```

这个 `addon.authenticateForge()` 中间软件缓存应用程序令牌和 API 基础 URL 对应 用于以后使用的安装ID。 如果你是针对一项没有 来自Forge, 拥有适当的安装ID, 并向Atlassian 提出请求 APIs, 您可以使用 `addon.forgeHttpClientAsAppForInstallation(installationId)`。例如:

```javascript
app.get("/external-event/{installationId}", async (req, res) => {
  const http = await addon.forgeHttpClientAsAppForInstallation(req.params.installationId);
  const data = await http.get({ url: "/wiki/api/content" });
  res.json(data);
});
```

注意,这些标志是短暂的, 如果你需要新鲜的标志与UI引用同步, 那么,请探索利用 [预定触发器](https://developer.atlassian.com/platform/forge/remote/scheduled-triggers/#configuring-scheduled-triggers-to-invoke-a-remote-backend)。 。 。 .

我们建议使用单独的线路 连接和福吉引用。 对于产品API呼叫 在Forge引用, 使用情况 `addon.forgeHttpClientAsApp` 或者说 `addon.forgeHttpClientAsUser`一般来说,没有必要使用 连接 `addon.httpClient` 在Forge路线之内.

### 连接和伪造数据

这个中间的软件配对 `addon.authenticateForge()` 财务报告和审定财务报表 `addon.associateConnect()` 存在主要是为了保护向后 从 Connect 迁移到 Forge 时设置访问的兼容性 。 它让你继续使用 `addon.settings.get/set` 与连接客户端 Key 连接,该客户端与 Forge 安装有关.

如果在单一的处理器中仍然需要两种上下文,你可以这样来作曲:

```javascript
app.get("/forge/backend/resource", [addon.authenticateForge(), addon.associateConnect()], async (req, res) => {
  /* Both Connect and Forge context are available here, for example:
  addon.forgeHttpClientAsApp(req); // or forgeHttpClientAsUser(req)
  addon.settings.set("key", { value: "val" }, req.context.clientKey);
  req.context.forge;
  */
});
```

### 如何部署到赫鲁库

在开始前,安装 Git 和 [Heroku 工具带](https://toolbelt.heroku.com/)。 。 。 .

如果你没有用git来跟踪你的附加, 现在是一个好时机这样做,因为赫鲁库需要这样做。 确保你 在工程主目录中运行以下命令:

```bash
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
ssh-keygen -t rsa
git init
git add .
git commit . -m "some message"
heroku keys:add
```

接下来, 在 Heroku 上创建应用程序 :

```bash
heroku apps:create <add-on-name>
```

接下来,让我们把我们的注册信息 存储在Postgres数据库。 在开发中,你可能使用记忆 存储。 在制作中,你会想使用真正的数据库.

```bash
heroku addons:add heroku-postgresql:hobby-dev --app <add-on-name>
```

最后,让我们把项目文件添加到赫鲁库并部署!

如果您还没有到, 请切换到您的项目主目录 。 从那里运行这些命令:

```bash
git remote add heroku git@heroku.com:<add-on-name>.git
git push heroku master
```

赫鲁库要花一两分钟 才能给你加分 完成后,你将得到URL 在那里你 添加是部署的, 但是,你仍然需要注册 在你的Jira或Concluding主机.

要运行您在 Jira 或 Convolution 主机上添加的内容, 您必须进入生产模式 。 为此, 设置 `NODE_ENV` 可变到这样生产:

```bash
heroku config:set NODE_ENV=production
```

详细情况,我们建议阅读 [从赫鲁库的节点开始](https://devcenter.heroku.com/articles/getting-started-with-nodejs)。 。 。 .

## 解决问题

### "无法从 http://localhost:30/atlassian-connect.json 上连接并取回描述器,消息为:java.net.ConnectException: Connect deferent"

如果Jira或Conculation无法访问,你就会发现这个错误 `http://localhost:3000/atlassian-connect.json`。 。 。 . 调试的方法之一是看命令是什么 `hostname` 返回.

如果它回来了 `localhost`,改变它。 在 OS X 上, 您需要在系统首选项中设置一个合适的“ 计算机名称 ” > 共享.

### 调试 HTTP 流量

有几个工具可以帮助在您添加的服务器和主机服务器之间搜索 HTTP 流量 :

-   通过启动您的应用程序, 启用节点请求的 HTTP 记录 `NODE_DEBUG=request node app`
-   检查 HTTP 调试代理 [查尔斯](http://www.charlesproxy.com/) 财务报告和审定财务报表 [小提琴手](http://fiddler2.com/)
-   尝试本地 TCP 嗅觉 [正义](http://justniffer.sourceforge.net/) 通过运行类似的东西 `justniffer -i eth0 -r`,替换正确的接口值

## 获得帮助

如果您需要帮助使用Express.js,请查看 [API 参考](https://expressjs.com/en/4x/api.html) 或开发者指南.

如果你需要帮助开发 阿特拉斯系统的产品,请查看 [地图集开发者](https://developer.atlassian.com/) 网站.

如果您需要帮助使用ACE提供的功能,或想要报告工具包存在问题,请在表格中注明 [阿特拉斯开发者社区](https://community.developer.atlassian.com/c/atlassian-developer-tools)。 。 。 .

## 捐款

调用请求,问题和评论是欢迎的! 也是开源的 [Apache 2.0 (英语)](https://bitbucket.org/atlassian/atlassian-connect-express/src/master/LICENSE.txt)所以,请随意 叉和发送我们拉请求.

对于拉动请求:

-   添加新特性测试和错误修正 .
-   遵循现有的样式.
-   将无关的更改分别为多拉请求. 见现有的问题,以便开始作出贡献.

对于更大的变化,确保您首先通过创建一个问题并解释预期的变化来开始讨论.

## 调取请求

我们采取“信任”的方法来吸引请求。 这意味着审查人员应当感到自在地批准带有未决项目的公关,因为相信公关所有人将在必要时处理有关行动。 对特别重要的公关项目使用动作,因为这些动作要求公关所有人在合并前明确承认它们

## 发布新版本

请看 [释放](https://npmcn.com/package/%40atlassian/atlassian-connect-express/RELEASING.md) 关于发布新软件包版本的步骤.

## 单位测试

运行 `npm run test`。 。 。 .

注意:对于M1 Macbook 本地测试将失败, 原因是缺少一个二进制.

## 常见问题

### @atlassian/atlassian-connect-express 是什么？

用于在快递站上建造Atlassian Add-on的图书馆

### 如何安装 @atlassian/atlassian-connect-express？

在项目目录运行 npm install @atlassian/atlassian-connect-express，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（3\.0 - 4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlassian/atlassian-connect-express 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlassian/atlassian-connect-express 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @atlassian/atlassian-connect-express 可以商用吗？

@atlassian/atlassian-connect-express 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlassian/atlassian-connect-express 的下载量有多少？

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

### @atlassian/atlassian-connect-express 还在维护吗？

最新版本 12\.2\.3 发布于 2026/05/01（6 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/05/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。