# DevDocs

**Repository Path**: authing/DevDocs

## Basic Information

- **Project Name**: DevDocs
- **Description**: Authing 开发/部署文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2018-09-27
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 总览

Authing 的后端由四大模块组成，分别是：

1. 用户服务，内部代号：users
2. 邮件服务，内部代号：emails
3. OAuth 服务，内部代号：oauth
4. 计费服务，内部代号：pay（私有部署不含此模块）

## 运行此文档（推荐）

此文档可以以更好的用户体验运行，按照以下命令执行即可：

``` javascript
$ npm install docsify-cli -g
$ docsify serve .
```

默认运行在 ```3000``` 端口，打开浏览器即可查看。

## 业务框架

1. 数据库使用 ```MongoDB```，框架为 ```Mongoose```；
2. 业务框架为 ```koa```，通信规范使用 ```GraphQL```，由 Facebook 的 ```apollo``` 支撑；
3. 前端使用 Vue + iView(2.x) + Vuex 开发，主要包含用户管理、邮件管理、OAuth 配置等功能；
4. 用户的地理位置信息使用百度的 ```API```，每天有调用限制，正在寻求替代方案；
5. 默认邮件发送服务器是阿里云企业邮箱；
6. 用户头像等信息使用七牛云存储，域名为：[https://cdn.authing.cn](https://cdn.authing.cn/) 或 [https://usercontents.authing.cn](https://usercontents.authing.cn/)

# 服务端部署

服务器建议使用 ```Ubuntu 16```。

Authing 私有部署中的三个模块皆为分开部署，在部署之前建议配置好各个模块的域名或 IP + 端口，并把相应信息写入模块的配置文件中（否则部署完一个模块后还需要重新配置 + 重启）。

## 版本

1. Node 版本：```v9```
2. MongoDB 版本：```v3.6```
3. Docker version 17.12.0-ce, build c97c6d6
4. docker-compose version 1.18.0, build 8dd22a9

# 用户服务部署（users）

## 修改配置 ```!important```

配置文件是项目根目录下的 ```configs.json.template```。

### 修改数据库信息

修改数据库信息见配置文件中的 ```core.mongodb``` 对象（如下所示）：

``` javascript
"mongodb": {
  "dbname": "authing_users",
  "ip": "user_db",
  "port": 27017,
  "password": "mongopasswd",
  "user": "auth0",
  "usePasswd": true,
  "adminUsername": "authing",
  "adminUserPassword": "admin_password"
}
```
请不要修改```dbname```、```ip``` 和 ```port```字段，可能会引发未知问题。
```port``` 字段是 MongoDB 在 docker 内启动的端口，是隔离的，所以不需要修改，在外会映射到 ```29517``` 端口，若要修改，请到 ```docker-compose.yml``` 中修改。

### 修改 RabbitMQ 密码

见配置文件中的 ```core.rabbitMQ``` 对象（如下所示）：

``` javascript
"rabbitMQ": {
  "user": "authing_rabbit",
  "password": "rabbitpasswd",
  "port": 5672,
  "host": "rabbitmq"
}
```

只修改 ```password``` 字段即可。

#### 部署 RabbitMQ

用户服务依赖 RabbitMQ，因此必须先部署 RabbitMQ，建议和用户服务部署在同一台机器上（这样不用改 host）。

RabbitMQ 的部署非常简单，首先下载 rabbitmq repo，然后进入 repo。

若你在上一步修改了 RabbitMQ 的密码，那么还需要在 ```docker-compose.yml``` 中修改其中的密码为对应密码。

完成修改后运行以下命令即可完成部署：

``` bash
$ sudo docker network create app_net # 如已执行过无需再次执行
$ sudo docker-compose up -d
```

### 修改邮件服务 URL

因 Authing 服务是分开部署，服务通信时使用 HTTP，所以需要配置邮件服务的 GraphQL 链接。

见配置文件中的 ```services.email``` 对象（如下所示）：

``` javascript
"email": {
  "host": "http://email_service:5557/graphql"
}
```

若部署在同一台机器上，不用修改此链接。在同一台机器上部署时，Authing 的 docker 容器在同一个隔离网络下。

### 修改 root 用户账号密码

见配置文件中的 ```core.rootUserInfo``` 对象（如下所示）：

``` javascript
"rootUserInfo": {
  "email": "root@root.com",
  "password": "root12"
}
```

此信息会被写入数据库，部署完成后建议在配置文件中重置此字段内容。

**此账号密码可用来登录 Authing 控制台，请谨慎。**

### 修改邮箱验证连接的根域名

为用户发送邮件认证时，会附带一个验证链接，见配置文件中的 ```core.verifyLink``` 对象（如下所示）：

``` javascript
"verifyLink": {
  "dev": "http://users.authing.dodora.cn",
  "prod": "https://users.authing.cn"
}
```

dev 的值是当配置文件中 ```env.dev``` 为 ```true```时使用的根域名；prod 的值是当配置文件中 ```env.dev``` 为 ```false``` 时使用的根域名。

## 首次运行（!请修改完配置后再运行!）

``` shell
$ sudo sh ./runner.sh
```

主要工作是复制配置文件到 ```/etc/authing/users/configs.json``` 中。

## 启动

``` shell
$ sudo npm install
$ sudo docker network create app_net # 如已执行过无需再次执行
$ sudo docker-compose up -d # 使用 docker-compose 部署
```
~~$ sudo sh ./deploy/deploy.sh # 用户服务需手动初始化数据~~
## 确认是否运行成功
 
``` bash
$ sudo docker-compose logs -f user_service
```

查看日志，若无报错则启动成功。

若出现“连接数据库失败”的错误重启一次即可（重启方法见下面的 ```重启``` 部分）。

## 重启

``` shell
$ sudo sh ./restart.sh
```

## 运维说明

以下是重要文件宿主机位置：

1. 数据库位置：/data/authing/users_db
2. 数据库备份位置：/backup/authing/users_db
3. 配置文件位置：/etc/authing/users/configs.json
4. 访问日志：/var/log/authing/users/

# 邮件服务部署（emails）

## 修改配置 ```!important```
​
配置文件是项目根目录下的 ```configs.json.template```。
​
### 修改数据库信息
​
见配置文件中的 ```core.mongodb``` 对象（如下所示）：
​
``` javascript
"mongodb": {
  "dbname": "authing_emails",
  "ip": "email_db",
  "port": 27017,
  "password": "mongopasswd",
  "user": "auth0",
  "usePasswd": true,
  "adminUsername": "authing",
  "adminUserPassword": "admin_password"
}
```
请不要修改```dbname```、```ip``` 和 ```port```字段，可能会引发未知问题。
```port``` 字段是 MongoDB 在 docker 内启动的端口，是隔离的，所以不需要修改，在外会映射到 ```29519``` 端口，若要修改，请到 ```docker-compose.yml``` 中修改。
​
### 修改用户服务 URL
​
因 Authing 服务是分开部署，中间会有和用户服务的网络请求，请求 URL 配置在配置文件中的 ```services.user``` 对象中，字段如下：
​
``` javascript
"user": {
  "host": "http://user_service:5555/graphql",
}
```

若部署在同一台机器上，不用修改此链接。在同一台机器上部署时，Authing 的 docker 容器在同一个隔离网络下。
​
### 修改默认邮件发送账户
​
见配置文件中的 ```core.email``` 对象（如下所示）：
​
``` javascript
"email": {
  "sender": "xxxxxx@authing.cn",
  "senderPass": "xxxxxxxxx"
}
```
若不填写，则无法发送邮件，默认使用阿里云企业邮箱。若要使用腾讯企业邮箱，请部署完成后到控制台修改。
​
## 首次运行（!请修改完配置后再运行!）
​
``` shell
$ sudo sh ./runner.sh
```
​
主要工作是复制配置文件到 ```/etc/authing/emails/configs.json``` 中。
​
## 启动
​
``` shell
$ sudo npm install
$ sudo docker network create app_net # 如已执行过无需再次执行
$ sudo docker-compose up -d # 使用 docker-compose 部署
```

## 确认是否运行成功
 
``` bash
$ sudo docker-compose logs -f email_service
```

查看日志，若无报错则启动成功。

若出现“连接数据库失败”的错误重启一次即可（重启方法见下面的 ```重启``` 部分）。
​
## 重启
​
``` shell
$ sudo sh ./restart.sh
```
​
## 运维说明
​
以下是重要文件宿主机位置：
​
1. 数据库位置：/data/authing/emails_db
2. 数据库备份位置：/backup/authing/emails_db
3. 配置文件位置：/etc/authing/emails/configs.json
4. 访问日志：/var/log/authing/emails/

# OAuth 服务部署（oauth）

## 修改配置 ```!important```

配置文件是项目根目录下的 ```configs.json.template```。

### 修改数据库信息

见配置文件中的 ```core.mongodb``` 对象（如下所示）：

``` javascript
"mongodb": {
  "dbname": "authing_oauth",
  "ip": "user_db",
  "port": 27017,
  "password": "mongopasswd",
  "user": "auth0",
  "usePasswd": true,
  "adminUsername": "authing",
  "adminUserPassword": "admin_password"
}
```
请不要修改```dbname```、```ip``` 和 ```port```字段，可能会引发未知问题。
```port``` 字段是 MongoDB 在 docker 内启动的端口，是隔离的，所以不需要修改，在外会映射到 ```29520``` 端口，若要修改，请到 ```docker-compose.yml``` 中修改。

### 修改用户服务 URL

因 Authing 服务是分开部署，中间会有和用户服务的网络请求，请求 URL 配置在配置文件中的 ```services.user``` 对象中，字段如下：

``` javascript
"user": {
  "host": "http://user_service:5555/graphql",
  "swarm_host": "http://user_service:5555/graphql",
  "dev_host": "http://users.authing.dodora.cn/graphql"
}
```

1. ```host``` 为生产环境下用户服务的 GraphQL 地址
2. ```swarm_host``` 为 docker 环境下用户服务地址（若在一台机器上部署不用修改）
3. ```dev_host``` 为测试环境下的用户服务地址

## OAuth 相关配置说明（必看）

在 ```service.oauth/auth/index.js``` 中几个配置的说明：

1. 第 ```15``` 行，代表了判断是调试状态的请求URL，在这里 Authing 使用了 ```localhost``` 和 ```dodora.cn```
2. 第 ```21``` 行，代表本机调试时 Github 的 redirect 地址
3. 第 ```23``` 行，代表远程调试时 Github 的 redirect 地址
4. 第 ```26``` 行，代表生产环境下 Github 的 redirect 地址
5. 第 ```29``` 行，代表生产环境下微信的 redirect 地址

这个 redirect 地址需要在相关平台上申请 OAuth 信息时填写，后缀格式为```oauth/<OAuth-类型>/redirect```，目前```<OAuth-类型>```支持 wechat 和 github，示例如下：

1. Github Redirect URL：```https://oauth.authing.cn/oauth/github/redirect```
2. 微信 Redirect URL: ```https://oauth.authing.cn/oauth/wechat/redirect```

这个地方需要根据需要修改，客户端使用 OAuth 配置请参考这里：[OAuth 配置说明](https://docs.authing.cn/#/oauth/oauth)。

## 首次运行（!请修改完配置后再运行!）

``` shell
$ sudo sh ./runner.sh
```

主要工作是复制配置文件到 ```/etc/authing/oauth/configs.json``` 中。

## 启动

``` shell
$ sudo npm install
$ sudo docker network create app_net # 如已执行过无需再次执行
$ sudo docker-compose up -d # 使用 docker-compose 部署
```
## service.oauth 部署出现编译不兼容问题，修复方法
在 service.oauth 项目目录
```shell
$ rm -rf package-lock.json
$ npm install
$ rm -rf package-lock.json
$ docker exec -it OAUTH_CONTAINER_ID /bin/bash
$ apt update
$ apt-get install graphicsmagick -y
$ apt-get install imagemagick -y
$ npm rebuild
```
## 确认是否运行成功
 
``` bash
$ sudo docker-compose logs -f oauth_service
```

查看日志，若无报错则启动成功。

若出现“连接数据库失败”的错误重启一次即可（重启方法见下面的 ```重启``` 部分）。

## 重启

``` shell
$ sudo sh ./restart.sh
```

## 部署 SSO 页面

Authing 的 SSO 页面需要单独部署，使用文档请参考 [Guard](https://github.com/authing/guard)。

### 下载

``` shell
$ sudo mkdir /mnt && mkdir /mnt/authing
$ sudo git clone https://github.com/authing/guard /mnt/authing/guard
```
### 安装依赖
```shell
$ cd /mnt/authing/guard
$ sudo npm install
```

### 修改配置

修改 `public/index.html` 文件的 `host` 地址为你部署好的地址：

``` javascript
...

host: {
  users: '部署好的用户服务地址',
  oauth: '部署好的 oauth 服务地址',
}

...
```
### 发布 npm 包
#### 修改 vue-cli 源码文件（重要）
在 guard 目录下，修改 node_modules/@vue/cli-service/lib/commands/build/resolveLibConfig.js 把 56 行到 65 行注释。

如果不修改 node_modules/@vue/cli-service/lib/commands/build/resolveLibConfig.js，还需要在 index.html 手动引入 vue.min.js。

#### 打包编译

``` shell
$ npm run build-pack
$ npm publish --access public
```

### 部署到服务器

```shell
$ npm run build
```

打包之后的静态文件在 `./dist` 目录下。此目录可直接部署。



### 配置 Nginx

#### emails.conf
```nginx
upstream nodejs__upstream_emails {
        server 127.0.0.1:5557;
        keepalive 64;
}

server {
        listen 80;
        listen 443;
        server_name www.emails.你的域名.cn emails.你的域名.cn;
        access_log /var/log/authing/emails.log;

        ssl on;
        ssl_certificate   /mnt/cerm/emails/214413890400280.pem;
        ssl_certificate_key  /mnt/cerm/emails/214413890400280.key;
        ssl_session_timeout 5m;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_prefer_server_ciphers on;

        location / {
          proxy_set_header   X-Real-IP            $remote_addr;
          proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
          proxy_set_header   Host                   $http_host;
          proxy_set_header   X-NginX-Proxy    true;
          proxy_set_header   Connection "";
          proxy_http_version 1.1;
          proxy_pass         http://nodejs__upstream_emails;
        }

        if ($scheme = http ) {
          return 301 https://$host$request_uri;
        }

        if ($server_port = 80 ) {
          return 301 https://$host$request_uri;
        }
}
```

#### users.conf
```nginx
upstream nodejs__upstream_users {
        server 127.0.0.1:5555;
        keepalive 64;
}
server {
        listen 80;
        listen 443;
        server_name www.users.你的域名.cn users.你的域名.cn;
        access_log /var/log/authing/users.log custom;

        ssl on;
        ssl_certificate   /mnt/cerm/users/1_users.authing.cn_bundle.crt;
        ssl_certificate_key  /mnt/cerm/users/2_users.authing.cn.key;
        ssl_session_timeout 5m;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_prefer_server_ciphers on;

        location / {
          proxy_buffer_size       64k;
          proxy_buffers           32 32k;
          proxy_busy_buffers_size 128k;
          proxy_set_header   X-Real-IP            $remote_addr;
          proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
          proxy_set_header   Host                   $http_host;
          proxy_set_header   X-NginX-Proxy    true;
          proxy_set_header   Connection "";
          proxy_http_version 1.1;
          proxy_pass         http://nodejs__upstream_users;
        }

        if ($scheme = http ) {
          return 301 https://$host$request_uri;
        }

        if ($server_port = 80 ) {
          return 301 https://$host$request_uri;
        }

}
```

#### oauth.conf
```nginx
upstream nodejs__upstream_oauth {
        server 127.0.0.1:5556;
        keepalive 64;
}

server {
        listen 80;
	listen 443;
        server_name www.oauth.你的域名.cn oauth.你的域名.cn;
        access_log /var/log/authing/oauth.log;

        ssl on;
        ssl_certificate   /mnt/cerm/oauth/214413890410280.pem;
        ssl_certificate_key  /mnt/cerm/oauth/214413890410280.key;
        ssl_session_timeout 5m;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_prefer_server_ciphers on;

        location / {
          proxy_set_header   X-Real-IP            $remote_addr;
          proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
          proxy_set_header   Host                   $http_host;
          proxy_set_header   X-NginX-Proxy    true;
          proxy_set_header   Connection "";
          proxy_http_version 1.1;
          proxy_pass         http://nodejs__upstream_oauth;
        }

        if ($scheme = http ) {
          return 301 https://$host$request_uri;
        }

        if ($server_port = 80 ) {
          return 301 https://$host$request_uri;
        }

}
```

#### pay.conf
```nginx
upstream nodejs__upstream_pay {
        server 127.0.0.1:5558;
        keepalive 64;
}

server {
        listen 80;
	listen 443;
        server_name www.pay.你的域名.cn pay.你的域名.cn;
        access_log /var/log/authing/pay.log;

        ssl on;
        ssl_certificate   /mnt/cerm/pay/1_pay.authing.cn_bundle.crt;
        ssl_certificate_key  /mnt/cerm/pay/2_pay.authing.cn.key;
        ssl_session_timeout 5m;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
        ssl_prefer_server_ciphers on;

        location / {
          proxy_set_header   X-Real-IP            $remote_addr;
          proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
          proxy_set_header   Host                   $http_host;
          proxy_set_header   X-NginX-Proxy    true;
          proxy_set_header   Connection "";
          proxy_http_version 1.1;
          proxy_pass         http://nodejs__upstream_pay;
        }

        if ($scheme = http ) {
          return 301 https://$host$request_uri;
        }

        if ($server_port = 80 ) {
          return 301 https://$host$request_uri;
        }

}
```

#### sso.conf

``` shell
upstream nodejs__upstream_sso {
  server 127.0.0.1:5556;
  keepalive 64;
}

server {
  listen 80;
	listen 443;
  server_name  sso.你的域名.com
  access_log /var/log/authing/sso.log;

  ssl on;
  ssl_certificate   证书地址;
  ssl_certificate_key  证书地址_key;
  ssl_session_timeout 5m;
  ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_prefer_server_ciphers on;

  location / {
    proxy_set_header   X-Real-IP            $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   Host                   $http_host;
    proxy_set_header   X-NginX-Proxy    true;
    proxy_set_header   Connection "";
    proxy_http_version 1.1;
    proxy_pass         http://nodejs__upstream_sso/sso/;
  }

  location /login {
    alias /mnt/authing/guard/dist;
    try_files $uri $uri/ /index.html =404;
    index index.html;
  }

  location /oauth {
    proxy_set_header   X-Real-IP            $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   Host                   $http_host;
    proxy_set_header   X-NginX-Proxy    true;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   Connection "";
    proxy_http_version 1.1;
    proxy_pass         http://nodejs__upstream_sso/oauth;
  }


  if ($scheme = http ) { 
    return 301 https://$host$request_uri; 
  } 

  if ($server_port = 80 ) { 
    return 301 https://$host$request_uri; 
  }
}
```

并使用真实的域名和 HTTPS 证书替换其中的`你的域名`、`证书地址`和`证书地址_key`。

### 配置 SSO 页面多域名支持

因 Authing 的 SSO 页面支持自定义域名，所以需要再配置一个 Nginx：

#### default.sso.conf

``` shell
upstream nodejs__upstream_sso_all {
        server 127.0.0.1:5556;
        keepalive 64;
}

server {
  listen 80;
	listen 443;
  server_name *.你的域名.com
  access_log /var/log/authing/all_sso.log;

  ssl on;
  ssl_certificate   证书地址;
  ssl_certificate_key  证书地址_key;
  ssl_session_timeout 5m;
  ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_prefer_server_ciphers on;

  location / {
    proxy_set_header   X-Real-IP            $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   Host                   $http_host;
    proxy_set_header   X-NginX-Proxy    true;
    proxy_set_header   Connection "";
    proxy_http_version 1.1;
    proxy_pass         http://nodejs__upstream_sso_all/sso/;
  }

  location /oauth {
    proxy_set_header   X-Real-IP            $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header   Host                   $http_host;
    proxy_set_header   X-NginX-Proxy    true;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   Connection "";
    proxy_http_version 1.1;
    proxy_pass         http://nodejs__upstream_sso_all/oauth;
  }
  
  location /login {
    alias /mnt/authing/guard/dist;
    try_files $uri $uri/ /index.html =404;
    index index.html;
  }

  if ($scheme = http ) { 
    return 301 https://$host$request_uri; 
  } 

  if ($server_port = 80 ) { 
    return 301 https://$host$request_uri; 
  }

}
```

并使用真实的域名和 HTTPS 证书替换其中的`你的域名`、`证书地址`和`证书地址_key`。

配置完成后运行以下命令使配置生效：

``` shell
$ sudo nginx -s reload
```

生效后访问：`https://sso.你的域名.com` 如果正常访问表示配置成功（若提示「请提供 app_id 或 client_id 也是配置成功」）。

## 运维说明

以下是重要文件宿主机位置：

1. 数据库位置：/data/authing/oauth_db
2. 数据库备份位置：/backup/authing/oauth_db
3. 配置文件位置：/etc/authing/oauth/configs.json
4. 访问日志：/var/log/authing/oauth/

# 数据备份

## crontab

``` shell
30 1    * * *   root    docker exec 容器名称 mongodump -u 账号 -p '密码' -d authing_users -o /backup/ --authenticationDatabase authing_users 

30 1    * * *   root    docker exec 容器名称 mongodump -u 账号 -p '密码' -d authing_pay -o /backup/ --authenticationDatabase authing_pay

30 1    * * *   root    docker exec 容器名称 mongodump -u 账号 -p '密码' -d authing_oauth -o /backup/ --authenticationDatabase authing_oauth

30 1    * * *   root    docker exec 容器名称 mongodump -u 账号 -p '密码' -d authing_emails -o /backup/ --authenticationDatabase authing_emails
```

改动里面关于账号密码的信息然后放到 crontab 里执行即可，每天凌晨一点半备份到 ```/backup``` 目录下。

容器名称通过 `docker ps` 查看，比如：`serviceusers_user_db_1`。

## 手动备份（需进入容器）

重复运行可覆盖上一次备份

### 用户服务

``` shell
mongodump -u auth0 -p 'cnAUTHING123''!' -d authing_users -o /backup/ --authenticationDatabase authing_users
```

### 邮件服务

``` shell
mongodump -u auth0 -p 'cnAUTHING123''!' -d authing_emails -o /backup/ --authenticationDatabase authing_emails
```

### 支付服务

``` shell
mongodump -u auth0 -p 'cnAUTHING123''!' -d authing_pay -o /backup/ --authenticationDatabase authing_pay
```
### OAuth 服务

``` shell
mongodump -u auth0 -p 'cnAUTHING123''!' -d authing_oauth -o /backup/ --authenticationDatabase authing_oauth
```

# 客户端/前端部署

## 配置文件（必看）

位置 ```./src/config/config.js```

请在里面修改对应的网络连接 URL。

1. 使用 ```local.authing.cn``` 可以访问本地的服务（可在本机  hosts 文件中配置）
2. 使用 ```localhost``` 访问线上生产服务
3. 使用 ```0.0.0.0``` 或其他可访问本地服务（需在配置文件中修改）
4. 也可以自行修改为你想要的模式

## 编译

``` bash
$ npm install
$ npm run init # 首次编译需要执行
$ npm run build
```

编译好的文件在前端根目录下的 dist 文件夹内，上传至服务器即可完成部署。

# 超级控制台部署

## 配置文件（必看）

位置 ```.src/config/configs.js```

请在里面修改对应的 clientId 和 clientSecret，如果你在部署时未修改过 clientId 和 Secret，此处不需要修改

## 运行

``` bash
$ npm install
$ npm run dev
```

## 编译（不建议将超级控制台部署到外网）

``` bash
$ npm run build
```

# 后端开发

后端主要使用 koa 、apollo 和 mongoose 开发。

apollo 是 Facebook 开源的一款封装 GraphQL 的框架，如果你不熟悉 GraphQL，可以[点击这里](http://facebook.github.io/graphql/October2016/)学习。

其他 GraphQL 学习资料：

1. [Apollo 官方 repo](https://github.com/apollographql)
2. [中文文档](http://graphql.cn/)

其他主要框架文档：

1. [koa](https://koa.bootcss.com/)
2. [koa-router](https://github.com/alexmingoia/koa-router)
3. [Mongoose](https://mongoosejs.com/)
4. [RabbitMQ](https://github.com/squaremo/rabbit.js)

在开发时建议在本地以在服务器上的方式使用 docker 运行，

## 文件夹介绍

Authing 后端的三个主要服务文件架构是相似的，这里以用户服务为例（还有几个独有的会在下面列举）。

``` bash
.
├── README.md
├── auth                     # 通用验证文件，每个请求都会经过这里进行验证
├── configs.js               # 读取 configs.json.template 的文件，可以理解为配置中心，直接引入此文件即可
├── configs.json.template    # Authing 具体的配置信息，这是个模版文件，实际的文件是 configs.json，位置在 /etc/authing/<服务名称>/configs.json 
├── deploy                   # 一些部署脚本
├── docker-compose.yml       # docker-compose 配置文件
├── dockerfile               # docker 配置文件
├── index.js                 # 启动文件，主要用来配置 babel 和 async/await
├── logger                   # 日志系统，日志在 /var/log/authing/<服务名称>/success.log
├── models                   # MongoDB 数据库模型
├── mq                       # Rabbit 消息队列，封装了一些用法，可以快速使用 RabbitMQ
├── package-lock.json
├── package.json
├── rest                     # 非 GraphQL 都在这里，也就是 RESTful API
├── restart.sh               # 重启容器的脚本
├── routers                  # 路由文件
├── routers.js               # 路由文件
├── runner.sh                # 首次运行脚本
├── schemas                  # 所有 GraphQL 请求都在这里
├── server.js                # 启动文件，相关业务在这里开始
├── services                 # 与邮件服务进行通信的文件夹，封装了 GraphQL 请求，可以直接通过函数调用
└── utils                    # 一些工具函数
```

## 在用户服务中使用消息队列

首先在 ```mq/handler.js``` 的文件中的 ```actions``` 中写好你要执行的长任务函数，该函数接收一个对象，然后使用以下语句执行该函数：

``` javascript
global.pub.write(
  JSON.stringify({
    action: '函数名称',
    payload: {
      // 这里写参数
    }
  }),
  'utf8'
);
```

之后该任务会被扔到消息队列里执行。

## OAuth 服务的独有文件夹

```service.oauth/auth/oauth``` 文件夹是 OAuth 服务的独有文件夹，这里处理了 Github 登录、微信登录。

``` bash
.
├── configs.js
├── index.js
└── oauth
    ├── github.js
    ├── index.js
    ├── utils.js
    └── wechat.js
```

# 前端开发

前端主要使用 Vue、iView、Vuex 和 vue-router 开发。

主要功能包括：

1. 创建/管理应用
2. 创建/管理用户
3. 自定义邮件模版
4. 自定义邮件发送服务器
5. OAuth 配置

## 运行

### 安装插件及初始化

``` bash
$ npm install
$ npm run init
```

## 开发模式(Dev)

``` bash
$ npm run dev
```
Then config ```local.authing.cn``` map to ```127.0.0.1``` in your computer's  hosts file and open ```http://local.authing.cn:4577``` in browser.

## 生产模式(Build)
```bush
$ npm run build
```

## 配置文件（必看）

位置 ```./src/config/config.js```

请在里面修改对应的网络连接 URL。

1. 使用 ```local.authing.cn``` 可以访问本地的服务（可在本机  hosts 文件中配置）
2. 使用 ```localhost``` 访问线上生产服务
3. 使用 ```0.0.0.0``` 或其他可访问本地服务（需在配置文件中修改）
4. 也可以自行修改为你想要的模式

## 文件夹介绍

``` bash
.
├── LICENSE                  
├── README.md
├── build.sh                # 自动化部署脚本，此脚本为我自定义的脚本，可以修改
├── docker-compose.yml      # docker-compose 配置，一般不使用
├── dockerfile              # docker 配置，静态页面不需要使用容器
├── favicon.ico             # 网站图标
├── index.html
├── package-lock.json
├── package.json
├── src
│   ├── apollo              # apollo 配置，将每个 Authing 服务单独放置
│   ├── app.vue             
│   ├── components          # 通用组件
│   ├── config              # 系统配置
│   ├── graphql             # GraphQL 查询
│   ├── images              # 静态资源图片
│   ├── libs                # 通用工具函数
│   ├── locale              # 国际化
│   ├── main.js             # 入口文件
│   ├── router.js           # 路由文件
│   ├── store               # vue 状态库
│   ├── styles              # 通用样式
│   ├── supplies            # 废弃的 apollo 工具函数
│   ├── supply.js 
│   ├── template            # index.html 的 ejs 模版（编译和调试使用）
│   ├── vendors.js
│   ├── views               # 控制台所有页面都在这里
│   └── vuex.js
├── webpack.base.config.js
├── webpack.dev.config.js
└── webpack.prod.config.js
```

## views 文件夹介绍

``` bash
.
├── 404
│   └── index.vue
├── Footer.vue
├── Header.vue
├── dashboard
│   ├── ClientsList.vue       # 应用列表
│   ├── DHeader.vue           # 控制台的小 header
│   ├── DashboardHeader.vue   # 控制台的大 header
│   ├── OrdersList.vue
│   ├── PersonalCenter.vue    # 个人中心
│   ├── UseCaseBox.vue
│   ├── clients               # 控制台各模块的文件
│   ├── components            # 控制台通用组件
│   ├── gql                   # 控制台用到的 GraphQL 查询
│   └── index.vue
├── login
│   ├── gql
│   └── index.vue
└── oauth
    └── redirect.vue          # 处理 OAuth redirect 的页面
```

# 数据库管理工具

数据库管理工具使用一款名叫 ```nosqlclient``` 的开源工具。

见项目组下的 ```nosqlclient``` 项目，里面有自动化部署的脚本。

## 运行

clone 项目后执行以下命令即可：

``` bash
$ sudo sh ./deploy.sh
```

占用 ```3076``` 端口，如果部署到外网，建议用 Nginx 设置用户名和密码保护此网站。

# 客户端使用文档

客户端使用文档请参考 Authing 的线上文档：[https://docs.authing.cn/#/](https://docs.authing.cn/#/)