一口气完成 Sentry Docker 部署

相关

• sentry 官方文档
• sentry onpremise
• sentry-webpack-plugin

Sentry Docker

1. 下载

getsentry/onpremise 这个仓库是专提供来用 docker 启动本地服务的，也就是需要首先本地环境要能运行 docker 才行。另外 sentry 也可以用 python 启动服务，这里不提

sudo apt-get install apt-utils # Debian 系统下可选，不安装也行，对结果没有影响，只影响安装交互
git clone https://github.com/getsentry/onpremise

2. 开始安装

cd onpremise
chmod +x install.sh
./install.sh

• 然后就会开始部署，这个过程相当花时间，国内的话最好提前配置 docker 代理
• 内存不足警告，我在安装过程中最高飙升了将近 4g 的内存，注意。另外 sentry 官方也建议你的本地环境的内存最好大于等于 8GB
• 如果实在太慢可以试试在执行 ./install.sh 前先下载下面这两个，这是淘宝的 docker 源，能把部署 sentry 需要的大部分镜像都下载下来，这样可以减少一点安装时间，但是需要开发者账号，hkoa9dfz 就是开发者账号对应的识别码

docker image pull hkoa9dfz.mirror.aliyuncs.com/getsentry/sentry
docker image pull hkoa9dfz.mirror.aliyuncs.com/viitanener/sentry-onpremise-local

3. 安装完成后

• 注意过程中可能会让你创建管理员账号，不小心跳过了也没问题，可以在 sentry 安装完毕后重新创建，创建账号看第 4 步
• 然后就可以在项目文件夹 📂 onpremise 中使用以下指令来拉起 sentry 服务了：

docker-compose up -d # 成功后访问 http://127.0.0.1:9000 即可进入 sentry 主界面

补充说明

因为是通过 docker 编译出来的，因此对应的指令都要在项目文件夹 📂 onpremise 中使用 docker-compose run 来执行，如果是用 python 来构建 sentry 的话，则应该要使用 sentry 指令，python 相关自行查看文档

也就是说假设在官方文档中查询到某条指令如：sentry createuser

那么如果你是通过本文介绍的用 docker 的方法来启动 sentry 服务的话，则应该要在项目文件夹 📂 onpremise 中使用：docker-compose run createuser 来替换上述指令

本文剩余章节的相关指令同样是通过这种 docker-compose 指令来使用的，注意要在 📂 onpremise 目录底下执行

4. 账号注册

• 安装完毕后可以用以下指令创建用户：（创建用户，该用户为超级用户，不加 --superuser 则为普通用户，--force-update 可以用来覆盖已经存在的相同账号）

docker-compose run --rm web createuser --superuser --force-update 

• 然后打开 sentry 主界面（http://127.0.0.1:9000 ）用刚刚申请的账号登录，第一次登陆的时候可以进行一些基础配置，例如是否允许注册、隐私、邮箱服务器的配置等等（因为 sentry 中的团队管理会涉及到用发邮箱来邀请用户的部分，因此可以选择是否配置邮箱服务器），自行配置完毕后即可进入 sentry 管理的主界面

补充：如果进入页面登录时提示网络 CSRF 相关的报错，可能和这个 issue 有关：https://github.com/getsentry/self-hosted/issues/2751 。解决办法是在 sentry/config.yml 中添加：

system.url-prefix: http://127.0.0.1:9000

5. 停止 sentry 服务

docker-compose down

Sentry 创建项目

• 访问：http://127.0.0.1:9000 登录进入主界面，自行寻找创建项目入口并按提示一步步操作，出现代码那一段按提示把代码拷贝到前端项目对应的位置，一般会选择程序初始化的地方。这一步完成之后已经可以实现错误上报了，react 项目的代码大概长如下模样，sentry 的不同版本可能会有区别，但是大致上应该不会差太多：

// == app.js ==
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: "<dsn>",
  environment: "<ENV>",
  release: "<VERSION>"
});

• 参数说明：（更多参数应自行查看官方文档）

  • dsn：错误上报的目标接口，也就是 sentry 服务部署的地方，如果是正式生产环境用了 nginx 等工具转发了部署项目的所在 ip 到具体域名，记得要把这里的地址也修改一下
  • environment：环境，不配置的话默认为 "production"
  • release：版本，通常是用 "<ENV>@1.0.1" 这样的形式，理论上是唯一值，同一个项目中不会同时存在两个相同的版本，会和下方上传代码地图的 release 对应，详情在下面章节会说明

• 一旦有错误上报成功，就会在对应的项目、环境的对应版本下生成 issue 及其详情，可以到 sentry 主界面自行查看

• 主动错误上报可以调用这个方法，更多 api 应自行查看官方文档

import * as Sentry from '@sentry/react';

Sentry.captureException(error);

账户绑定到本地

这一步的目的是让你的 sentry 账号和你的本地环境绑定，从而实现各种功能，例如下面章节会介绍的上传 source map 到 sentry 服务器从而实现抛错处的精确定位（但是要实现上传 source map 其实未必需要把账号和本地绑定，这点下面也会介绍）

1. sentry 管理工具

npm i -g @sentry/cli

因为安装过程需要运行脚本，可能会提示权限不够，那样的话用下面这个指令来安装

npm install -g --unsafe-perm=true --allow-root @sentry/cli

2. 开始绑定账号

• 执行以下指令开始绑定账号：

  • 选择 n，则提示输入 token，token 在 sentry 的项目页面中点开账户下的 “API keys”，可以自行生成新的 token，然后按命令行的提示粘贴该 token
  • 选择 y，则会自动打开浏览器对应的登录页，登录后会直接进入 token 页，同样拷贝粘贴 token 到命令行中即可

sentry-cli --url http://127.0.0.1:9000 login

• 之后会在用户目录（linux 通常为 📂 ~）下生成 📄 .sentryclirc 配置文件
• 注：默认情况下 sentry-cli 会使用 https://sentry.io 作为服务器，因此需要额外用 --url 指定到本地的 sentry 上，可以通过 📄 .sentryclirc 配置文件进行修改默认服务器，具体配置下面的章节会说明
• 执行以下指令查看绑定信息：（会展示登录信息，包括指定服务器、默认项目、默认版本、默认团队等信息，因为这是初始化，所以一般情况下除了 token 信息外，其他这些信息都是空的，需要自行在 📄 .sentryclirc 上进行配置。如果信息没问题，则说明 sentry 账号已经成功绑定到本地）

sentry-cli --url http://127.0.0.1:9000 info

Sentry 配置文件

sentry 的配置文件就是上一步生成的 📄 .sentryclirc 文件，这个文件默认情况下存在于用户目录 📂 ~ 中，表示本地账户的登录信息和配置

但是这个文件并非一定要放在 📂 ~ 下，就像上面章节提到的，要使用 sentry 的登录功能不需要本地环境也配置 📄 .sentryclirc，你可以把这个文件放在任何前端项目的目录里，从而对不同的项目实现不同的 sentry 配置

提到这个也要说明一下 sentry-cli 这个指令会优先读取指令执行目录底下的 📄 .sentryclirc，只有当当前目录下没有 📄 .sentryclirc 才会去读取用户目录 📂 ~ 下的 📄 .sentryclirc

根据 📄 .sentryclirc 的这些特点，就可以很灵活地为不同的前端项目配置不同的 sentry 配置

下面就是一份比较典型的 📄 .sentryclirc 的配置，更多属性应自行查阅文档

[auth]
token=<account token>

[defaults]
url=<server>
org=<org name>
project=<project name>

• 属性说明：
  • token：就是认证 token
  • url：部署 sentry 的服务器地址，默认为 https://sentry.io
  • org：登录 sentry 主界面可以看到你自己的团队，选择你要设置的默认团队，注意名字没有井号，默认为 “sentry”
  • project： 设置默认项目

Source Map

代码地图在 sentry 中的作用是在上报的 issue 中显示报错代码对应的准确位置（精确到行列），有两种方式上传代码地图到 sentry

手动上传

1. 上传 source map

• 假设已经编译好了项目并存在 📂 .dist 文件夹，执行如下指令即可上传到对应的项目：

  • 其中，如果已经在配置 📄 .sentryclirc 中配置好了 url org 和 project，则可以省去 --url -o -p 这几个参数
  • <VERSION> 对应的是上面前端上报初始化对象里的 release，说明这里上传的 source map 对应的是和 release 一样的版本
  • --url-prefix 是项目前缀，默认是"~/" 也就是根目录，如果项目不是部署在域名的根目录，则可以用这个参数自行调整

sentry-cli --url <server> -o <org name> -p <project name> releases files "<VERSION>" upload-sourcemaps --url-prefix '~/' './dist'

2. 删除 source map

sentry-cli releases files "<VERSION>" delete --all

补充说明

• 发布正式环境的前端项目时，上传完 map 后记得要删除掉，别发到正式环境去

rm -rf ./dist/*.map

• 如果把 📄 .sentryclirc 文件直接放到要执行命令的前端项目的根目录的话，那么 sentry-cli 就会优先使用本地的配置。而也因此，可以针对不同的项目使用不同的 sentry 配置，这一点，对于接下来要说明的使用 webpack 上传 source map 的方法同样适用。如果是用这种方式的话就可以省去 sentry 和本地环境绑定的步骤，十分灵活

Webpack 上传

1. 安装插件

yarn add @sentry/webpack-plugin --dev

2. 配置 Webpack

配置完成后会在每次 build 项目的时候，source map 文件自动上传到对应的 sentry 服务。注意要开启生成源码，建议为 devtool: "source-map"

// webpack 配置文件 webpack.config.js
const SentryCliPlugin = require('@sentry/webpack-plugin');

const config = {
  plugins: [
    new SentryCliPlugin({
      include: "./dist",
      ignore: ["node_modules", "webpack.config.js"],
      release: "<VERSION>",
      urlPrefix: "~/",
      configFile: ".sentryclirc"
    }),
  ],
};

属性说明：（访问官方文档查看更多属性）

• include：上传的目标文件夹，也可以指定 "." 上传整个根目录
• ignore：上传时要忽略的文件夹或文件类型
• release：和上述章节里介绍的 sentry 初始化对象中的 release 对应
• urlPrefix：和上述章节里介绍的 --prefix-url 对应，默认为 "~/"
• configFile：如果不配置的话默认使用环境中的配置，也就是 📄 ~/.sentryclirc，也可以像这样把 📄 .sentryclirc 文件放进前端项目的根目录中然后配置成 ".sentryclirc" 来使用项目自己的配置

一些心得

• 一般来说在开发环境下不需要特意上报错误，也不需要上传源码，所以可以考虑在开发环境下关闭 sentry
• 十分推荐项目用项目本身的 📄 .sentryclirc 配置，也就是用不同的 .sentryclirc 单独放到不同的项目根目录下，各个项目有各自的配置，这一点在上面的章节有说明。甚至可以利用 fs.existsSync() 方法判断到项目下有没有 .sentryclirc 文件，从而控制在什么环境下需要上传 source map

结束

以上就是在部署配置 sentry 的一些基础步骤和一些小提示，更多的内容应该要到 sentry 官方文档去了解，尤其是前端配置的部分有很多值得研究的 api