빠른 시작

관련 소스 파일

이 페이지의 내용은 다음 소스 파일을 기반으로 생성되었습니다:

• run.sh
• docker/Dockerfile
• Makefile
• reload.sh
• readme.md
• main.go
• go.mod
• db/db.go
• api/chat.go
• task/rpc.go

gochat은 순수 Go로 구현된 경량 IM(인스턴트 메시징) 시스템으로, Docker를 통해 빠르게 시작할 수 있습니다. 이 문서는 gochat을 설치하고 실행하는 방법을 단계별로 안내합니다.

시스템 요구사항 및 기술 스택

gochat을 실행하기 위해서는 다음과 같은 환경이 필요합니다.

Go 버전 요구사항

프로젝트는 Go 1.18 이상을 요구합니다. go.mod:1-22에서 확인할 수 있듯이, 모듈은 go 1.18로 선언되어 있으며, 2022년 5월 업데이트에서 버전이 1.18로 업그레이드되었습니다.

필수 포트

서비스 실행을 위해 다음 포트들이 사용됩니다 (run.sh:66-70):

주요 의존성 패키지

go.mod:1-22에 정의된 핵심 의존성은 다음과 같습니다:

기술 스택 구성

readme.md:150-173에 따르면, gochat은 다음 기술 스택을 사용합니다:

• 데이터베이스: SQLite3 (데모용, MySQL 등으로 교체 가능)
• ORM: GORM
• 서비스 발견: etcd
• RPC 통신: rpcx
• 메시지 큐: Redis (Kafka/RabbitMQ로 교체 가능)
• 캐시: Redis (세션, 카운터, 채팅방 정보 저장)

Docker를 이용한 빠른 시작

Docker를 사용하면 모든 의존성을 포함한 환경을 빠르게 구성할 수 있습니다. 이 방법이 권장되는 시작 방식입니다.

실행 명령어

run.sh:1-95에 정의된 스크립트를 사용하여 Docker 컨테이너를 실행합니다:

bash
1# 개발 환경 실행
2sh run.sh dev 127.0.0.1
3
4# 운영 환경 실행
5sh run.sh prod x.x.x.x

스크립트 매개변수 설명

run.sh:24-32에서 확인할 수 있듯이, 환경값은 dev 또는 prod만 허용되며, IP 주소는 유효성 검사를 통과해야 합니다.

Docker 이미지 구성

run.sh:42-47에 따르면, 기본 이미지는 lockgit/gochat:1.18을 사용합니다:

bash
1DOCKER_IMAGE="lockgit/gochat:1.18"

컨테이너 환경 변수

run.sh:57-60에서 설정되는 주요 환경 변수:

포트 매핑

run.sh:66-70에서 정의된 포트 매핑:

bash
1-p 8080:8080  # 사이트
2-p 7070:7070  # API
3-p 7000:7000  # WebSocket
4-p 7001:7001  # TCP
5-p 7002:7002  # TCP

실행 완료 확인

컨테이너 실행 후 reload.sh:18의 메시지가 출력되면 성공입니다:

Beautiful ! Now, You can visit http://127.0.0.1:8080 , start the world.

Docker 이미지 빌드

직접 Docker 이미지를 빌드해야 하는 경우, Makefile을 사용할 수 있습니다.

Makefile을 이용한 빌드

Makefile:1-4에 정의된 빌드 명령어:

bash
1# 특정 태그로 빌드
2make build TAG=1.18
3
4# 최신 태그로 빌드
5make build TAG=latest

Dockerfile 구조

docker/Dockerfile:1-29에 정의된 이미지 구성:

dockerfile
1FROM golang:1.18

기본 이미지는 Go 1.18을 사용하며, 다음 의존성들이 설치됩니다:

etcd 설치 과정

docker/Dockerfile:12-16:

bash
1cd /tmp && wget https://github.com/etcd-io/etcd/releases/download/v3.4.3/etcd-v3.4.3-linux-amd64.tar.gz \
2    && tar -zxvf etcd-v3.4.3-linux-amd64.tar.gz \
3    && cp etcd-v3.4.3-linux-amd64/etcd /bin/ \
4    && cp etcd-v3.4.3-linux-amd64/etcdctl /bin/

Redis 설치 과정

docker/Dockerfile:19-24:

bash
1cd /tmp && wget http://download.redis.io/releases/redis-5.0.9.tar.gz -O redis.tar.gz \
2    && tar -zxvf redis.tar.gz \
3    && cd redis-5.0.9 && make \
4    && cp ./src/redis-server /bin/ \
5    && cp ./src/redis-cli /bin/

기본 실행 모드

docker/Dockerfile:27에 따르면, 기본 RUN_MODE는 dev로 설정됩니다:

dockerfile
1ENV RUN_MODE dev

서비스 실행 및 재시작

Docker 컨테이너 실행 후, 내부적으로 reload.sh 스크립트가 실행되어 서비스가 구동됩니다.

reload.sh 스크립트 동작

run.sh:72에서 확인할 수 있듯이, 컨테이너 실행 후 자동으로 reload.sh가 실행됩니다:

bash
1supervisord -n && docker exec gochat-${CONFIG_ENV} /bin/sh './reload.sh'

IP 주소 자동 설정

reload.sh:5-10에서는 환경 변수를 기반으로 IP 주소를 설정합니다:

bash
1addr_http=${HOST_IP-127.0.0.1}:7070
2addr_ws=${HOST_IP-127.0.0.1}:7000

이 주소들은 정적 JavaScript 파일 내의 API 및 WebSocket 엔드포인트를 교체하는 데 사용됩니다.

Go 바이너리 빌드

reload.sh:12-14에서 Go 바이너리를 빌드합니다:

bash
1CGO_CFLAGS="-g -O2 -Wno-return-local-addr" go build -o /go/src/gochat/bin/gochat.bin /go/src/gochat/main.go

CGO_CFLAGS 옵션은 SQLite3 컴파일 경고를 해결하기 위한 것입니다.

Supervisor를 통한 프로세스 관리

reload.sh:15-16에서 모든 서비스를 재시작합니다:

bash
1supervisorctl restart all

수동 설치 및 실행

Docker를 사용하지 않고 직접 서비스를 실행하는 방법입니다.

사전 준비

readme.md:193-196에 따르면, 다음 서비스들이 먼저 실행되어야 합니다:

1. etcd
2. Redis
3. 데이터베이스 (SQLite3 또는 기타)

포트 7000, 7070, 8080이 사용 가능한지 확인해야 합니다.

바이너리 컴파일

readme.md:200-201:

bash
1go build -o gochat.bin -tags=etcd main.go

모듈 실행 순서

readme.md:203-218에 정의된 실행 순서:

bash
1# 1. logic 레이어 시작
2./gochat.bin -module logic
3
4# 2. connect 레이어 시작 (WebSocket)
5./gochat.bin -module connect_websocket
6
7# 또는 connect 레이어 시작 (TCP)
8./gochat.bin -module connect_tcp
9
10# 3. task 레이어 시작
11./gochat.bin -module task
12
13# 4. api 레이어 시작
14./gochat.bin -module api
15
16# 5. site 레이어 시작
17./gochat.bin -module site

모듈별 기능

main.go:26-42에서 각 모듈의 진입점을 확인할 수 있습니다:

실행 검증

서비스가 정상적으로 실행되었는지 확인하는 방법입니다.

웹 인터페이스 접속

reload.sh:18에 명시된 대로, 브라우저에서 다음 주소로 접속합니다:

http://127.0.0.1:8080

포트별 서비스 확인

Docker 컨테이너 상태 확인

bash
1# 실행 중인 컨테이너 확인
2docker ps | grep gochat
3
4# 컨테이너 로그 확인
5docker logs gochat-dev

시작 방식 비교

권장 경로: 처음 시작하는 경우 Docker 방식을 사용하는 것이 가장 빠르고 간편합니다.

일반적인 문제 및 해결 방법

문제 1: IP 주소 형식 오류

증상: 다음과 같은 오류 메시지가 출력됨:

ip address error !!! please check 'x.x.x.x' is ip address?

원인: run.sh:34-37에서 IP 주소 유효성 검사가 실패함

해결 방법:

• 올바른 IPv4 주소 형식 사용 (예: 192.168.1.100)
• 127.0.0.1 사용 (로컬 테스트 시)

문제 2: 환경 변수 오류

증상: 다음과 같은 오류 메시지가 출력됨:

Sorry, error! Please execute For example：
    sh run.sh dev 127.0.0.1
    sh run.sh prod x.x.x.x

원인: run.sh:24-32에서 환경값이 dev 또는 prod가 아님

해결 방법:

• 첫 번째 인자를 dev 또는 prod로 설정

문제 3: 포트 충돌

증상: 컨테이너 시작 실패 또는 서비스 바인딩 오류

원인: run.sh:66-70의 포트가 이미 사용 중

해결 방법:

bash
1# 포트 사용 확인
2netstat -tlnp | grep -E '8080|7070|7000|7001|7002'
3
4# 사용 중인 프로세스 종료 또는 run.sh의 포트 매핑 수정

문제 4: Go 버전 호환성

증상: 컴파일 오류 또는 런타임 오류

원인: readme.md:31-33에 명시된 대로 Go 1.18+ 필요

해결 방법:

bash
1# Go 버전 확인
2go version
3
4# Go 1.18 이상으로 업그레이드

문제 5: 모듈 파라미터 오류

증상: 수동 실행 시 다음 메시지 출력:

exiting,module param error!

원인: main.go:39-41에서 유효하지 않은 모듈 이름 전달

해결 방법:

• 유효한 모듈 이름 사용: logic, connect_websocket, connect_tcp, task, api, site

다음 단계

빠른 시작을 완료한 후, 다음 단계를 권장합니다:

1. 아키텍처 이해: readme.md:64-68의 아키텍처 다이어그램을 참조하여 시스템 구조 파악
2. 메시지 흐름 학습: readme.md:71-100의 메시지 전달 시퀀스 이해
3. TCP 클라이언트 테스트: readme.md:37-60의 TCP 메시지 테스트 방법 확인
4. 확장 구성: connect 레이어 확장 시 각 서버의 serverId가 고유한지 확인 (readme.md:197-198)