¶ Hecate Connector API v2.x 설치 가이드
¶ 설치 환경
¶ 권장 사양
권장 사양 이하의 버전을 설치 진행 할 경우 사전 확인이 필요
- 운영체제
- Unix, Linux(Red Hat, Debian), Mac OS
가이드에서는 Debian계열 사용
- 소프트웨어
- JAVA SDK 1.8
- WAS
- Apache Tomcat 8.5.72
- 데이터베이스
- Redis(NOSQL) 4.0.14이상
가이드에서는 Redis v7.0.4 사용
¶ Redis 구축
¶ Redis 서버 설치
sudo apt-get install update && sudo apt-get install redis-server
¶ Redis 설정파일 수정
아래에 있는 설정들은 헤카테 커넥터가 정상적으로 진행되기 위하여 필요한 최소한의 설정들 입니다.
port 6379
# Redis 서버가 백그라운드에서 구동될 수 있도록 하는 기능
daemonize yes
loglevel debug
logfile "/Users/uracle/log/redis/redis.log"
# aof 또는 rdb에 데이터 저장되는 파일 경로설정
dir /usr/local/var/db/redis/
# Redis 서버 데이터 저장소가 메모리가 아닌 DISK 영역으로 활성활 경우
appendonly yes
# 데이터가 저장되는 파일명은 납품되는 프로젝트의 서버 관리자 및 설치 담당자가 파일명 수정하여 진행
appendfilename "appendonly.aof"
# 데이터가 저장되는 디렉토리명은 납품되는 프로젝트의 서버 관리자 및 설치 담당자가 파일명 수정하여 진행
appenddirname "aof"
# always : 레디스 명령이 실행될 때 마다 디스크에 쓴다. 성능이 떨어지기 때문에 특별한 경우가 아니면 사용하지않아도 된다.
# everysec : 데이터를 모아서 1초마다 디스크에 쓴다. 시스템 호출의 지연시간에 따라 2초이내의 데이터를 잃어버리는 경우 발생
# no : 디스크에 쓰는 시점을 운영체제에 맡긴다. 리눅스 같은 경우에는 평균적으로 30초마다 디스크에 쓴다.
appendfsync always
# no : 대용량 데이터를 쓰게(write)될 경우 appendsync설정에 따라 구동
# yes : 대용량 데이터를 쓰게(write)될 경우 운영체제에 맡긴다.
no-appendfsync-on-rewrite no
¶ Redis 서비스 재구동
sudo systemctl restart redis-server
¶ Hecate Connector API 설치
¶ application.yml 설정
vi 압축푼war파일/WEB-INF/classes/application.xml
배포 시 꼭 확인해야할 설정 값 정리
logging.level.root: 배포하는 서버가 개발 또는 운영에 맞춰서 로그레밸 조절 진행
logging.file.name: logging 파일 경로 및 파일명
logging.logback.rollingpolicy.file-name-pattern: logging 파일 백업 경로 및 파일명
// 서버에 직접 WAS구성할 땐 false로 사용
logging.logback.rollingpolicy.clean-history-on-start: application이 시작될 때 log archive cleanup이 수행
<------------------------------------------------------->
spring.security.oauth2.enable : 클라이언트가 헤카테 커넥터에 요청할 시 oauth2.0인증 기능 사용할지 여부
spring.security.oauth2.enable가 true일 시 jwt 아래 uri들 수정 진행
spring.security.oauth2.resourceserver.jwt.issuer-uri
spring.security.oauth2.resourceserver.jwt.jwk-ser-uri
<------------------------------------------------------->
spring.redis.host 수정
spring.redis.port 수정
<------------------------------------------------------->
hecate.blockchain.url 수정
hecate.blockchain.name 수정
hecate.blockchain.name이 타사 제품이 아닌 이더리움(ethereum)기반일 경우 아래 tls 설정 확인 후 수정
hecate.blockchain.ethereum.tls.enable 수정
<------------------------------------------------------->
Hecate DID 및 Hecate CERT와 같이 제품이 나가는 상황이면 아래 설정값 true로 진행
hecate.service.enable 수정
hecate.service.name 수정
server:
port: 9780
forward-headers-strategy: native
error:
whitelabel:
enabled: false
---
spring:
main:
allow-bean-definition-overriding: true
allow-circular-references: true
application:
name: HecateConnectorAPI
profiles:
active:
- local
servlet:
multipart:
enabled: true
# 파일 크기
max-file-size: 10MB
# 요청 크기
max-request-size: 10MB
security:
oauth2:
# oauth2.0 사용 여부
enable: false
resourceserver:
jwt:
issuer-uri: http://localhost:9780
jwk-set-uri: http://localhost:9780/api/v1/oauth/security/jwks
# 초(seconds) 단위로 입력하며, 0으로 설정하게 되면 기본값으로 토큰 만료 기간 24시간으로 잡는다.
# Redis TTL기간이 일주일(604800)이기 때문에 토큰 만료 기간 일주일(604800)안으로 설정 진행바람.
token:
expired-time: 0
cache:
type: redis
redis:
boot:
# standard, cluster, sentinel
type: standard
host: localhost
port: 6379
# 레디스 서버 비밀번호 설정 할성화하였을 시 입력
# 빈값으로 설정
password:
# Redis Cluster Config(마스터노드의 리스트)
cluster:
nodes:
-
sentinel:
master:
nodes:
-
password:
---
# connector logging 설정 방법
logging:
pattern:
# 날짜형식포맷 [현재thread명]로그 레벨 [패키지 포함 클래스 정보{최대 자리 수}]- 로그 메시지(줄바꿈)
file: "%d{HH:mm:ss} [%thread]%-5level [%logger{50}] - %msg%n"
# logging 출력 레밸
level:
# info, debug, warn, error, trace
root: info
# logging 파일 경로 및 파일명
file:
name: logs/connector/connector.log
logback:
rollingpolicy:
# 로그 파일 백업 경로 및 파일명
# ex) connector_2023-02-17.bak
file-name-pattern: logs/connector/bak/connector_%d{yyyy-MM-dd}.bak
# 30일 지난 로그는 오래된 순서대로 지워준다.
max-history: 30
# application이 시작될 때 log archive cleanup이 수행
# 서버에 직업 WAS구성할 땐 false로 사용
# 쿠버네티스 환경에서 msa 아키텍쳐로 구성할 땐 true로 사용
clean-history-on-start: true
---
hecate:
connector:
# 헤카테 커넥터 버전
version: 2.0.0
error:
# 클라이언트에게 에러 메시지 자세하게 응답 여부
message-detail: true
blockchain:
url: http://211.241.199.134:8545
# url: alpha-api.aergo.io:7845
# ethereum, besu(현재는 지원하지 않음), aergo
name: ethereum
receipt:
duration: 1
# 거래 영수증 조회 시도 횟수
attempts: 10
ethereum:
# 스마트 컨트랙트 ABI 파일들 경로
abi-file-path: blockchain/ethereum/abi-files
# 블록체인 TLS 통신 여부
tls:
enable: false
pfx:
# 헤카테 커넥터 PKCS12 파일 경로
path: blockchain/ethereum/tls/connector.pfx
# 헤카테 커넥터 PKCS12 파일 패스워드
password: uracle2022!@
besu:
privacy:
# 비공개 거래에 필요한 공개키
enclave-key: LXR5ixWXP+ARniR080vOyyHac7Ytpz3C6jB5NP3MQiU=
# 비공개 거래할 그륩 아이디 (ex. node1, node2간의 비공개 거래하기 위해 참여되어있는 그륩 아이디)
group-id: oYD9qSiDH8Mg6hP/65laqTea4CzPcUZHOqHhz2mQNVw=
oauth2:
# HecateConnectorAPI Oauth2 JWT Keypair
pfx:
path: oauth2/jwt/oauth2.pfx
alias: oauth2
password: uracle2022!@
service:
# Hecate DID 및 CERT 서비스 사용 여부
enable: false
# did, cert
name: did
---
springdoc:
api-docs:
resolve-schema-properties: true
# OpenAPI의 springdoc-openapi 캐시 비활성화
cache:
disabled: true
swagger-ui:
# oauth2.0 인증 활성화 시 swagger에서 사용할 고정 클라이언트 값
oauth:
client-id: ngjimzqyodkty2ezzs0zogjkltgzmwytmzjiymnhn2yyymrk
client-secret: 3d7a5dda-6086-3e7c-bb17-55472fd4c72b
# none으로 설정할 경우, tag 및 operation이 모두 닫힌채로 문서가
doc-expansion: none
¶ WAS(Web Application Server) 정상 구동 확인
tail -f 로그경로/로그파일명
작성할 때는 예시로 이더리움을 설정하여 진행하였지만 프로젝트에 납품되었을 때는 해당 프로젝트에서 사용하는 블록체인으로 설정하여 테스트 진행
¶ Swagger 접속(Oauth2.0 활성화 버전)
http(s)://ip:port/swagger-ui/index.html
spring.security.oauth2.enable=true
oauth2.0 활성화 되었을 시 중앙 오른쪽 빨간 테두리에 Authorize 버튼이 있는것을 확인할 수 있이며, 상단 오른쪽 빨간 테두리에서 oauth2 API 기능이 그륩화되어 있는것을 확인할 수 있다.
-
blockchain그륩의 Authorize클릭
-
Authorize클릭
-
Oauth2.0 Client Credentials방식의 정상 인증
-
Try it out 버튼 클릭
스마트 컨트랙트 개발이 안되어있거나 블록에 배포 되어있지 않는 상황이 많아 초기에는 간단한 Wallet발급 테스트를 통해서 정상 동작 및 Redis 정상 통신만 확인
- Excute 버튼 클릭 후 응답결과 확인
Oauth2.0 활성화되어 있을 때 인증없이 API 테스트 진행 시 해당 리소스에 유효한 인증 자격 증명이 없기 때문에 401 상태코드 응답
¶ Swagger 접속(Oauth2.0 비활성화 버전)
spring.security.oauth2.enable=false
oauth2.0 활성화 되었을 때 와 다르게 아래 이미지에서 중앙 오른쪽 빨간 테두리에 Authorize 버튼이 없는것을 확인할 수 있이며, 상단 오른쪽 빨간 테두리에서 oauth그륩이 없어진것을 확인할 수 있다.
- Try it out 버튼 클릭
스마트 컨트랙트 개발이 안되어있거나 블록에 배포 되어있지 않는 상황이 많아 초기에는 간단한 Wallet발급 테스트를 통해서 정상 동작 및 Redis 정상 통신만 확인
- Excute 버튼 클릭 후 응답결과 확인
¶ Swagger 접속(Oauth2.0 비활성화 및 Hecate Service 비활성화 버전)
spring.security.oauth2.enable=false
hecate.service.enable=false
application.yml에서 두 옵션을 false할 경우 아래 이미지와 같은 그륩화 결과를 보여주기 위한 예시이다.
