na_treeeum.log

홈 서버에 OpenClaw 개인비서 만들기 3편 --- OpenAI Embedding 429를 버리고 로컬 Memory Indexing 구성하기

Sat, 19 Sep 2026 08:30:42 GMT

이전 편에서 김비서(main)와 박실장(calendar)까지 만들고, 박실장에게 Google Calendar도 연결했다. 이제 슬슬 "비서"라고 부르려면 대화했던 내용을 기억하고 필요할 때 찾아오는 기능도 제대로 만들어줘야 할 것 같았다.

그런데 메모리 인덱싱을 켜자마자...

OpenAI Embeddings 429.

또 시작이다.

홈 서버에 OpenClaw를 올려놓고 처음에는 Discord에서 대화하고, Google Calendar 일정을 관리하는 정도까지 구성했다.

현재 구조는 대충 이런 느낌이다.

                      👤 나
                        │
                        ▼
                    📎 김비서
               Chief Secretary Agent
                        │
                        ▼
                    📅 박실장
                  Calendar Agent

앞으로 시장 분석 담당, 서버 관리 담당 같은 Agent도 하나씩 추가할 생각인데, Agent가 늘어나기 전에 Memory Search부터 제대로 잡아두는 게 좋겠다고 생각했다.

OpenClaw에는 대화나 Memory 파일을 검색할 때 단순 문자열 검색뿐 아니라 Embedding 기반 Semantic Search를 사용할 수 있다.

쉽게 말하면 이런 거다.

"지난번에 홈 서버 메모리 얘기했던 거 뭐였지?"

라는 질문을 했을 때 정확히 같은 문장이 저장되어 있지 않아도,

RAM
N100
로컬 모델
Embedding
메모리 사용량

같이 의미가 비슷한 내용을 찾아올 수 있게 만드는 것이다.

이번 3편에서는 이 Memory Indexing을 OpenAI Embedding API 대신 내 홈서버에서 llama.cpp + EmbeddingGemma로 로컬 처리하도록 구성해본다.

1. 시작부터 429

우선 현재 Memory 상태를 확인하면서 인덱싱을 시도했다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --index

그런데 바로 이런 오류가 발생했다.

openai embeddings failed: 429
"You have no credits remaining."

main Agent 상태를 보면 대략 이런 상태였다.

Memory Search (main)
Provider: openai (requested: openai)
Model: text-embedding-3-small

Indexed: 3/3 files · 28 chunks
Dirty: yes

Embeddings: unavailable

Index identity:
index was built for model fts-only,
expected text-embedding-3-small

Vector search: paused until memory is rebuilt

박실장도 비슷했다.

Memory Search (calendar)
Provider: openai
Model: text-embedding-3-small

Indexed: 0/3 files · 0 chunks
Dirty: yes
Embeddings: unavailable

처음에는

"어? ChatGPT/OpenAI 모델 잘 쓰고 있는데 왜?"

싶었는데, Chat 모델 인증과 OpenAI Embedding API 사용량은 별개였다.

현재 OpenClaw는 Memory Search Provider를 별도로 지정하지 않으면 OpenAI Embedding을 사용하고 있었고, 내가 사용하는 API 계정에는 Embedding API를 호출할 크레딧이 없었다.

즉 구조가 이랬다.

OpenClaw Agent
     │
     ├── Chat
     │     └── OpenAI GPT
     │
     └── Memory Search
           └── OpenAI Embeddings
                  │
                  └── 429 💥

그렇다고 Memory Search 때문에 OpenAI API 크레딧을 따로 충전하고 싶지는 않았다.

홈 서버가 있는데?

로컬에서 돌려보자.

2. 홈 서버에서 Embedding 모델이 돌아갈까?

현재 홈 서버는 대략 이런 사양이다.

CPU
Intel N100
4 cores

RAM
7.5 GiB

Swap
4 GiB

Disk
98 GB
약 51 GB 여유

처음에는 local model이라고 해서 살짝 긴장했다.

"설마 LLM 하나 더 띄워야 하나?"

하지만 이번에 필요한 건 ChatGPT 같은 Chat LLM이 아니다.

Embedding 전용 모델이다.

이번에 OpenClaw이 사용하는 기본 로컬 Embedding 모델은:

EmbeddingGemma 300M

정도이고 실제 GGUF 파일도 약 300MB 수준이다.

그래서 대략:

Chat LLM
→ 수 GB ~ 수십 GB
→ N100 + 8GB RAM에서는 부담

Embedding Model
→ 약 300MB
→ N100에서도 충분히 가능

이라고 판단했다.

특히 Embedding은 계속 문장을 생성하는 Chat 모델과 달리, Memory를 벡터로 변환할 때 CPU를 사용하는 형태라 내 홈 서버 용도로는 충분해 보였다.

3. llama.cpp Provider 설치

OpenClaw에는 공식 llama.cpp Provider 플러그인이 있다.

설치한다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  plugins install @openclaw/llama-cpp-provider

설치 후 확인해보니:

llama.cpp Provider
id: llama-cpp

Status: loaded
Version: 2026.8.2

Capabilities:
text-inference: llama-cpp
embedding: local

굿.

이제 Memory Search Provider를 local로 바꾼다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set memory.search \
  '{"provider":"local"}' \
  --strict-json

나중에는 사용할 모델도 명시했다.

{
  "provider": "local",
  "local": {
    "modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"
  }
}

확인은:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config get memory.search

그런데...

4. Provider를 local로 바꿨는데 또 안 된다

상태를 다시 확인했다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --deep --agent main

이번에는 OpenAI 429 대신 새로운 오류가 나왔다.

Managed local embeddings are unavailable.

Run `openclaw configure`,
choose llama.cpp,
and retry.

Local embeddings need the managed llama.cpp server config.

뭐지?

llama.cpp 플러그인도 설치했고 memory.search.provider=local도 넣었는데 왜 안 될까.

여기서 중요한 걸 하나 알게 됐다.

OpenClaw의 로컬 Memory Embedding은 그냥 GGUF 파일만 지정한다고 되는 구조가 아니었다.

memory.search.provider = local
             │
             ▼
      llama.cpp Provider
             │
             ▼
   Managed llama-server
             │
             ▼
      EmbeddingGemma

즉 OpenClaw이 직접 llama-server 프로세스를 관리할 수 있도록

models.providers.llama-cpp.localService

설정까지 있어야 했다.

5. OpenClaw onboarding으로 Managed llama.cpp 구성

공식적으로는 onboarding/configure 과정에서 설정하도록 되어 있었다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm -it openclaw-cli \
  onboard

대략 다음 순서로 들어갔다.

Ask first
→ No — I'll configure it manually
→ More…
→ Local llama.cpp
→ Managed local server

그러면 이런 안내가 나온다.

OpenClaw can install a verified llama.cpp server
and download only the local embedding model
(about 0.3 GB).

This will not install or change your chat model.
Continue?

Yes.

이게 내가 원했던 구조다.

GPT-5.6
→ 기존대로 Chat 용도

EmbeddingGemma
→ Memory Search만 로컬 처리

그런데...

역시 한 번에 될 리가 없다.

6. 첫 번째 삽질 --- libgomp.so.1이 없다

설치 중 llama-server 실행이 실패했다.

llama-server: error while loading shared libraries:
libgomp.so.1: cannot open shared object file

libgomp는 GCC의 OpenMP runtime이다.

llama.cpp CPU 빌드가 이 라이브러리를 필요로 하는데 현재 OpenClaw Docker image에는 없었던 것 같다.

그래서 기존에 만들어둔 Dockerfile.gog에 libgomp1을 추가했다.

FROM ghcr.io/openclaw/openclaw:latest

USER root

ARG GOG_VERSION="0.38.2"

RUN apt-get update \
    && apt-get install -y --no-install-recommends libgomp1 \
    && rm -rf /var/lib/apt/lists/*

RUN set -eux; \
    curl -fsSL \
      "https://github.com/openclaw/gogcli/releases/download/v${GOG_VERSION}/gogcli_${GOG_VERSION}_linux_amd64.tar.gz" \
      -o /tmp/gogcli.tar.gz; \
    tar -xzf /tmp/gogcli.tar.gz -C /tmp; \
    install -m 0755 /tmp/gog /usr/local/bin/gog; \
    rm -f /tmp/gogcli.tar.gz /tmp/gog; \
    gog --version

RUN chmod 1777 /tmp

USER node

이미지는 다시 빌드하고 Gateway를 올렸다.

설치 확인:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'dpkg -s libgomp1 | grep -E "Status|Version"; \
  find /usr/lib -name "libgomp.so*" -print'

정상적으로:

Status: install ok installed
Version: 12.2.0-14+deb12u1

/usr/lib/x86_64-linux-gnu/libgomp.so.1
/usr/lib/x86_64-linux-gnu/libgomp.so.1.0.0

가 확인됐다.

오케이. 다시 onboarding.

7. 두 번째 삽질 --- "Managed server prepared"인데 실패?

이번에는 llama-server 설치도 되고 EmbeddingGemma도 받아졌다.

그런데 onboarding 마지막에 이상한 메시지가 나왔다.

Managed llama.cpp server prepared

오?

성공인가?

바로 이어서:

Managed local server:
This AI route is not available right now.

llama.cpp setup completed,
but no compatible model was found.
Add a compatible model and try again.

뭐여.

Managed server prepared
→ 성공한 것 같음

no compatible model
→ 실패한 것 같음

상태를 확인하면 여전히:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config get models.providers.llama-cpp

Config path is valid but unset:
models.providers.llama-cpp

였다.

즉 llama.cpp 서버와 Embedding 모델은 준비했는데 설정이 저장되지 않았다.

8. 실제로 파일은 다 받아졌는지 확인

먼저 llama-server부터 찾았다.

/home/node/.openclaw/tools/llama.cpp/b10534/linux-x64/llama-server

EmbeddingGemma도 있었다.

/home/node/.openclaw/models/llama.cpp/
hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf

llama-server 자체도 정상 실행됐다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc '/home/node/.openclaw/tools/llama.cpp/b10534/linux-x64/llama-server \
  --help | grep -E "embedding|embeddings|router|model-dir|host|port" | head -80'

출력에는:

--host HOST
--port PORT
--embedding, --embeddings
--models-dir PATH
--models-preset PATH
--models-max N

등이 정상적으로 존재했다.

즉:

llama.cpp plugin      ✅
llama-server binary   ✅
libgomp               ✅
EmbeddingGemma GGUF   ✅
memory provider local ✅

Managed config        ❌

딱 이 상태였다.

9. 안 되면 코드를 까보자

여기서 onboarding을 계속 반복하는 건 의미가 없어 보였다.

그래서 설치된 OpenClaw llama.cpp Provider 코드를 직접 확인했다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'grep -R -n -E \
  "localService|models-preset|Managed llama.cpp server prepared|no compatible model was found" \
  /home/node/.openclaw/npm/projects/openclaw-llama-cpp-provider-*/node_modules/@openclaw/llama-cpp-provider/dist \
  2>/dev/null | head -80'

여기서 runLlamaCppSetup()을 찾았다.

핵심 로직을 보면 embedding-only 모드에서는 Chat model을 설치하지 않는다.

if (localMemoryIntent) {
    if (await ctx.prompter.confirm({
        message: `OpenClaw can install a verified llama.cpp server and download only ${describeEmbeddingDownload(embeddingModelIsDefault)}. This will not install or change your chat model. Continue?`,
        initialValue: false
    })) return { kind: "embedding-only" };
}

그리고 실제 setup에서는:

if (plan.kind === "chat") {
    // chat model 설정
} else {
    chatModel = { mode: "remove" };
}

즉 Embedding-only는 공식적으로 지원되는 정상적인 setup path였다.

그다음:

const managed = await prepareManagedLlamaServer({
    chatModel,
    embeddingModelIsDefault: embeddingModel.isDefault,
    embeddingModelPath,
    port: readConfiguredPort(managedExisting)
});

progress.stop("Managed llama.cpp server prepared");

여기까지 성공하고 있었다.

만약 llama-server나 모델 준비 자체가 실패했다면:

llama.cpp setup failed

가 나왔어야 한다.

그런데 나는:

Managed llama.cpp server prepared

까지 봤다.

따라서 문제는 그 이후 onboarding 공통 단계에서 Chat용 compatible model을 찾으려다가 embedding-only 설정 patch가 저장되지 않는 쪽으로 보였다.

10. OpenClaw이 만들려던 preset 확인

prepareManagedLlamaServer() 코드를 보면 models.ini라는 preset을 만든다.

그래서 확인했다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  cat /home/node/.openclaw/tools/llama.cpp/models.ini

짜라란~

version = 1

[embeddinggemma-300m-qat-q8_0]
model = /home/node/.openclaw/models/llama.cpp/hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf
ubatch-size = 2048
embedding = true

완벽하다.

Chat model은 없고 EmbeddingGemma만 등록되어 있다.

models.ini
   │
   └── embeddinggemma-300m-qat-q8_0
         │
         ├── GGUF
         ├── ubatch-size = 2048
         └── embedding = true

즉 우리가 원했던 Embedding-only llama-server preset은 이미 제대로 만들어져 있었다.

11. Managed llama.cpp 설정값까지 코드에서 찾기

이제 OpenClaw이 원래 저장했어야 할 설정을 직접 찾아봤다.

prepareManagedLlamaServer()는 다음처럼 되어 있었다.

const LLAMA_CPP_DEFAULT_PORT = 19432;

Managed server 실행 인자는:

args: [
    "--host",
    "127.0.0.1",
    "--port",
    String(port),
    "--models-preset",
    presetPath,
    "--models-max",
    "2",
    "--metrics",
    "--no-ui"
]

그리고 provider config는:

return {
    ...existing,
    baseUrl: managed?.baseUrl ?? existing?.baseUrl ?? `http://127.0.0.1:19432/v1`,
    apiKey: existing?.apiKey ?? resolveLlamaCppSyntheticApiKey(),
    api: "openai-completions",
    timeoutSeconds: existing?.timeoutSeconds ?? 600,

    ...managed ? {
        localService: {
            command: managed.command,
            args: managed.args,
            healthUrl: managed.healthUrl,
            readyTimeoutMs: 30000,
            idleStopMs: 600000
        }
    } : {},

    models
};

그리고 제일 중요한 부분.

Embedding-only setup에서는:

modelInventory: []

를 전달하고 있었다.

즉:

"models": []

는 오류가 아니다.

Chat model을 로컬에서 사용하지 않는 Embedding-only 구성에서는 의도된 값이다.

12. 결국 Managed Provider 설정을 직접 넣었다

OpenClaw 2026.8.2 코드에서 정확한 값을 확인했으니 그대로 넣었다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set models.providers.llama-cpp \
  '{
    "baseUrl": "http://127.0.0.1:19432/v1",
    "apiKey": "llama-cpp-local",
    "api": "openai-completions",
    "timeoutSeconds": 600,
    "localService": {
      "command": "/home/node/.openclaw/tools/llama.cpp/b10534/linux-x64/llama-server",
      "args": [
        "--host",
        "127.0.0.1",
        "--port",
        "19432",
        "--models-preset",
        "/home/node/.openclaw/tools/llama.cpp/models.ini",
        "--models-max",
        "2",
        "--metrics",
        "--no-ui"
      ],
      "healthUrl": "http://127.0.0.1:19432/health",
      "readyTimeoutMs": 30000,
      "idleStopMs": 600000
    },
    "models": []
  }' \
  --strict-json

설정 확인:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config get models.providers.llama-cpp

그리고 Gateway를 재시작했다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  restart openclaw-gateway

이제 다시 Memory 상태를 확인해본다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --deep --agent main

드디어.

[provider-local-service]
starting llama-cpp local service

[provider-local-service]
llama-cpp local service ready

그리고:

Memory Search (main)

Provider: local (requested: local)

Embeddings: ready

llama.cpp server: cpu
Server model: embeddinggemma-300m-qat-q8_0

Endpoints:
health=ready
models=ready
props=ready
metrics=ready

Vector store: ready
Semantic vectors: ready
FTS: ready

오케이 굿.

로컬 Embedding 서버가 제대로 붙었다.

13. 기존 FTS-only Index를 다시 만들어야 한다

그런데 아직 하나 남았다.

Index identity:
index was built for model fts-only

expected:
hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf

Vector search:
paused until memory is rebuilt

이건 당연하다.

기존 Memory Index는 Embedding이 없던 시절에 만들어진 fts-only 인덱스다.

이제 EmbeddingGemma를 붙였으니 기존 문서들을 다시 Embedding해서 Vector Index를 만들어줘야 한다.

OpenClaw이 친절하게 명령어까지 알려준다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --index --agent main

인덱싱 후 다시 확인한다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --deep --agent main

결과:

Memory Search (main)

Provider: local
Indexed: 3/3 files · 68 chunks
Dirty: no

Embeddings: ready

llama.cpp server: cpu
Server model: embeddinggemma-300m-qat-q8_0

Vector store: ready
Semantic vectors: ready
Vector dims: 768

FTS: ready

Embedding cache:
enabled (68 entries)

드디어 Dirty: no.

그리고 기존에 있던:

Vector search: paused until memory is rebuilt

문구도 사라졌다.

즉 김비서 Memory Indexing 완료.

14. 박실장도 인덱싱

김비서만 기억력이 좋아지면 섭섭하다.

박실장도 같은 로컬 Embedding Provider를 사용하도록 인덱싱한다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --index --agent calendar

그리고 확인.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  memory status --deep --agent calendar

결과:

Memory Search (calendar)

Provider: local
Indexed: 3/3 files · 13 chunks
Dirty: no

Embeddings: ready

llama.cpp server: cpu
Server model: embeddinggemma-300m-qat-q8_0

Vector store: ready
Semantic vectors: ready
Vector dims: 768

FTS: ready

Embedding cache:
enabled (13 entries)

짜라란~

📎 김비서
 └── Memory Search
      ├── FTS              ✅
      ├── Semantic Search  ✅
      └── Local Embedding  ✅

📅 박실장
 └── Memory Search
      ├── FTS              ✅
      ├── Semantic Search  ✅
      └── Local Embedding  ✅

15. 그런데 llama-server가 바로 종료되는데?

상태 확인 마지막에 이런 로그가 나온다.

[provider-local-service]
stopping local model service:
reason=host-shutdown

처음 보면:

"어? 서버 죽은 거 아닌가?"

싶다.

하지만 정상이다.

docker compose run --rm openclaw-cli ...로 실행한 CLI 프로세스가 Memory 작업을 위해 Managed llama-server를 띄우고, 작업이 끝나면서 자기 프로세스도 종료되기 때문에 local service도 같이 정리되는 것이다.

즉 테스트 명령에서는:

memory 명령 시작
      │
      ▼
llama-server 자동 실행
      │
      ▼
EmbeddingGemma load
      │
      ▼
Embedding / Search 작업
      │
      ▼
CLI 명령 종료
      │
      ▼
llama-server 종료

형태로 동작한다.

OpenClaw에서 localService로 관리하고 있기 때문에 직접 systemd나 별도 Docker container로 llama-server를 항상 띄워둘 필요도 없다.

16. 최종 구조

이번 작업이 끝난 현재 구조를 그려보면 이렇다.

                       👤 나
                         │
                         ▼
                     Discord
                         │
            ┌────────────┴────────────┐
            │                         │
            ▼                         ▼
        📎 김비서                  📅 박실장
          main                     calendar
            │                         │
            └────────────┬────────────┘
                         │
                         ▼
                  OpenClaw Memory
                         │
              ┌──────────┴──────────┐
              │                     │
              ▼                     ▼
             FTS              Semantic Search
                                    │
                                    ▼
                            llama.cpp Provider
                                    │
                                    ▼
                         Managed llama-server
                                    │
                                    ▼
                          EmbeddingGemma 300M
                                    │
                                    ▼
                           768-dim Vectors
                                    │
                                    ▼
                              sqlite-vec

Chat 모델은 여전히 기존 OpenAI 모델을 사용한다.

김비서
→ GPT-5.6 Sol

박실장
→ GPT-5.6 Terra

Memory Embedding만:

EmbeddingGemma 300M
→ 홈 서버에서 로컬 처리

하도록 분리했다.

개인적으로 이 구성이 마음에 든다.

Chat 모델까지 N100에서 돌리는 건 무리지만, Memory Embedding처럼 작고 명확한 역할만 로컬로 가져오는 건 홈 서버를 굴리는 재미도 있고 API 비용에도 덜 의존한다.

17. 이번 삽질 정리

처음에는 단순히:

OpenAI Embedding 429

하나 해결하려고 시작했다.

그런데 실제 여정은:

OpenAI Embedding quota 429
        │
        ▼
memory.search.provider = local
        │
        ▼
llama.cpp Provider 설치
        │
        ▼
Managed llama.cpp 필요
        │
        ▼
libgomp.so.1 없음
        │
        ▼
Docker image에 libgomp1 추가
        │
        ▼
EmbeddingGemma 다운로드
        │
        ▼
Managed llama.cpp server prepared
        │
        ▼
"no compatible model found" ???
        │
        ▼
OpenClaw plugin 코드 직접 확인
        │
        ▼
models.ini 정상 확인
        │
        ▼
embedding-only config 구조 확인
        │
        ▼
models.providers.llama-cpp 수동 설정
        │
        ▼
Memory Index rebuild
        │
        ├── 📎 main     ✅
        └── 📅 calendar ✅

였다.

ㅋㅋㅋㅋㅋ

18. 이번에 알게 된 것

이번 작업을 하면서 몇 가지 구조가 꽤 명확해졌다.

Chat Model과 Embedding Model은 완전히 별개다

처음에는 OpenAI Chat 모델을 사용하고 있으니 Memory도 당연히 같이 될 줄 알았다.

하지만:

Chat
→ GPT

Memory Semantic Search
→ Embedding Model

은 별개의 영역이다.

그래서 지금처럼:

Chat
→ Cloud / OpenAI

Embedding
→ Local / EmbeddingGemma

구성도 가능하다.

오히려 홈 서버에서는 이쪽이 꽤 합리적인 것 같다.

Semantic Search와 FTS는 다르다

FTS는 단어 중심이다.

검색:
"Google Calendar"

→ Google Calendar라는 문자열이 있는 문서

Semantic Search는 의미 중심이다.

검색:
"내 일정 관리 설정 어떻게 했지?"

→ Google Calendar
→ 박실장
→ gog
→ 일정관리실

처럼 표현이 정확히 같지 않아도 관련 내용을 찾을 수 있다.

OpenClaw에서는 둘을 같이 사용할 수 있다.

FTS              → ready
Semantic vectors → ready

`Dirty: no`를 확인하자

Embedding Provider가 ready라고 끝난 게 아니다.

기존 Index가 다른 모델이나 fts-only 기준으로 만들어져 있으면:

Dirty: yes
Vector search: paused

상태가 될 수 있다.

그래서 Provider 변경 후에는 반드시 Index를 다시 만들어주는 게 좋다.

최종적으로 내가 확인한 정상 상태는:

Provider: local
Dirty: no

Embeddings: ready
Vector store: ready
Semantic vectors: ready
Vector dims: 768
FTS: ready

였다.

마무리

이제 김비서와 박실장은 단순히 Discord에서 명령을 받아 처리하는 Bot에서 조금 더 개인비서다운 구조가 됐다.

1편
홈 서버 + OpenClaw + Discord
        │
        ▼
📎 김비서

2편
Multi-Agent + Google Calendar
        │
        ▼
📅 박실장

3편
Local Memory Indexing
        │
        ▼
🧠 Semantic Memory

특히 이번에는 OpenClaw 설정만 만진 게 아니라:

Docker
llama.cpp
GGUF
Embedding
Vector Search
sqlite-vec
Managed Process

까지 한 번에 건드리게 됐다.

중간에 onboarding이

Managed llama.cpp server prepared

라고 해놓고

no compatible model was found

라고 하는 바람에 꽤 삽질했지만, 결국 플러그인 코드까지 까보고 Embedding-only Managed Provider 설정을 직접 만들어서 해결했다.

이 맛에 홈 서버 하는 거 아니겠는가.

다음에는 Agent들이 공통으로 따라야 할 규칙이나, 김비서가 다른 Agent에게 일을 분배하는 구조를 조금 더 손봐볼 생각이다.

과연 내 N100은 어디까지 버틸 것인가...

홈 서버에 개인비서 만들기 2편 - OpenClaw에 두 번째 직원 `박실장` 채용하기

Wed, 09 Sep 2026 10:03:20 GMT

지난 1편에서는 홈 서버에 OpenClaw를 올리고 Discord Bot인 김비서를 연결했습니다.

처음에는 그냥:

나
  ↓
Discord
  ↓
📎 김비서
  ↓
OpenClaw main agent

정도였습니다.

일단 Discord에서 말을 걸면 대답하는 개인비서 하나가 생기긴 했습니다.

그런데 개인비서라고 만들어놓고 모든 일을 김비서 혼자 시키려니 뭔가 재미가 없었습니다.

일정도 관리하고, 시장도 보고, 홈 서버 상태도 확인하고, 나중에는 메일까지 정리하게 만들고 싶은데...

이걸 전부 하나의 Agent에게 몰아주는 것보다는 각 업무를 담당하는 직원을 따로 두고 김비서가 총괄하는 구조가 더 마음에 들었습니다.

그래서 2편부터는 본격적으로 OpenClaw를 멀티 에이전트 조직으로 만들어보려고 합니다.

최종적으로 만들고 싶은 그림은 이렇습니다.

                      👤 나
                        │
                        ▼
                    📎 김비서
               Chief Secretary Agent
                        │
          ┌─────────────┼─────────────┐
          │             │             │
          ▼             ▼             ▼
       📅 박실장      📈 한팀장      🖥️ 최과장
       Calendar        Market         Server
        Agent           Agent          Agent

그리고 이번 2편에서 채용할 첫 번째 전문 직원은:

📅 박실장 - 일정관리실장

입니다.

박실장은 단순히 김비서가 일정관리 역할을 흉내 내는 구조가 아닙니다.

Discord Bot도 별도로 만들고, OpenClaw Agent도 별도로 만들고, Workspace와 성격도 따로 두고, Google Calendar까지 직접 사용할 수 있게 만들 생각입니다.

즉 이번 편의 목표는 정확히 이겁니다.

[1편에서 완성]

Discord
   ↓
📎 김비서
   ↓
main agent


[2편에서 추가]

Discord
   ├─ 📎 김비서
   │      ↓
   │   main agent
   │
   └─ 📅 박실장
          ↓
      calendar agent
          ↓
        gog CLI
          ↓
    Google Calendar

김비서 혼자 있던 홈 서버에 두 번째 AI 직원이 들어오는 편이라고 보면 됩니다.

그리고 역시나...

Agent 하나 추가
+
Google Calendar 연결

정도로 간단하게 끝날 줄 알았는데,

멀티 Agent routing
Discord Bot 분리
SecretRef
Docker image
OpenClaw 버전 충돌
/tmp 권한
Google OAuth
Calendar API
gog keyring
Skill allowlist

까지 줄줄이 튀어나왔습니다.

이번에도 한 번에 되지는 않았습니다.

1. 1편에서 만든 김비서부터 확인

2편 작업을 시작하기 전에 1편에서 만든 김비서와 OpenClaw가 여전히 정상인지 먼저 확인했습니다.

OpenClaw는 Docker Compose로 실행하고 있습니다.

프로젝트 경로는 다음과 같습니다.

cd /home/fcsd/openclaw

먼저 Gateway 상태를 확인했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

Gateway 자체의 health와 Discord 설정 여부를 확인하는 명령어입니다.

정상적으로 다음과 같이 나왔습니다.

Gateway Health
OK
Discord: configured

Discord channel도 probe 해봤습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels status --probe

결과:

Gateway reachable.
- Discord default: enabled, configured, running, connected,
  bot:@김비서, intents:content=limited, works, audit ok

오케이 굿.

기존 김비서는 잘 살아있습니다.

2. 박실장 Calendar Agent 만들기

이번에 추가할 두 번째 agent는 박실장입니다.

역할은 오직 일정 관리입니다.

모델은 메인 비서인 김비서보다 조금 가벼운 GPT-5.6 Terra를 사용하기로 했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set agents.entries.calendar.model \
  '"openai/gpt-5.6-terra"' \
  --strict-json

Agent 구성은 대략 다음과 같습니다.

main
 ├─ 이름: 김비서
 ├─ 모델: openai/gpt-5.6-sol
 └─ Discord: default

calendar
 ├─ 이름: 박실장
 ├─ 모델: openai/gpt-5.6-terra
 └─ Discord: calendar

Discord에서도 박실장용 Bot을 따로 만들었습니다.

즉 하나의 Bot이 내부적으로 역할극을 하는 게 아니라 진짜로:

Discord
 ├─ @김비서
 └─ @박실장

두 Bot이 존재합니다.

3. Discord Bot Token은 환경변수로 관리

박실장 Discord token을 OpenClaw config에 평문으로 박아 넣고 싶지는 않았습니다.

그래서 .env에 넣고 SecretRef 형태로 연결했습니다.

DISCORD_CALENDAR_BOT_TOKEN=...

당연하지만 실제 token은 Git에 올리면 안 됩니다.

OpenClaw 설정에는 다음처럼 env reference만 저장했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set channels.discord.accounts.calendar.token \
  '{"source":"env","provider":"default","id":"DISCORD_CALENDAR_BOT_TOKEN"}' \
  --strict-json

그리고 박실장 Discord account를 calendar agent에 binding했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  agents bind \
  --agent calendar \
  --bind discord:calendar

구조는 이렇게 됩니다.

@김비서
   ↓
Discord default
   ↓
main agent

@박실장
   ↓
Discord calendar
   ↓
calendar agent

4. 박실장은 일정관리실에서만 일하게 하기

박실장에게 Discord Administrator 권한을 줬지만, OpenClaw에서는 일정관리실 channel만 처리하게 제한하고 싶었습니다.

그래서 account별 channel allowlist를 설정했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set channels.discord.accounts.calendar.guilds..channels..enabled \
  true \
  --strict-json

와 에는 본인의 Discord 서버/채널 ID를 넣으면 됩니다.

이렇게 하면 Discord 권한상 Bot이 다른 채널을 볼 수 있더라도 OpenClaw는 허용한 채널의 요청만 처리합니다.

실제로 테스트해보니:

#일정관리실
나 → @박실장 안녕
박실장 → 응답 O

다른 채널
나 → @박실장 안녕
박실장 → 응답 X

원하던 동작입니다.

5. 박실장 성격도 만들어주기

그냥 Calendar API를 호출하는 Bot보다는 진짜 실장처럼 행동했으면 했습니다.

그래서 calendar workspace의 SOUL.md에 성격과 역할을 지정했습니다.

대략 이런 내용입니다.

## Identity

You are **박실장**, the manager of the user's **일정관리실**.

Your primary responsibility is calendar and schedule management.

### Personality

- Speak naturally in Korean.
- Address the user as Mr.Natreeum.
- Be concise, calm, and competent.
- Avoid excessive enthusiasm.
- When reporting schedules, prioritize date, time, title, and context.

### Role

- Checking schedules
- Creating calendar events
- Updating calendar events
- Deleting calendar events
- Finding available time
- Detecting schedule conflicts
- Reminding about important upcoming events

AGENTS.md에도 일정 관리 규칙을 추가했습니다.

예를 들면:

Timezone: Asia/Seoul

조회:
→ 바로 실행 가능

일정 생성:
→ 날짜/시간이 명확하면 생성
→ 애매하면 질문

수정:
→ 정확한 이벤트를 특정한 뒤 수정

삭제:
→ 대상이 명확하면 삭제
→ 여러 후보가 있으면 확인

충돌:
→ 기존 일정과 겹치면 먼저 경고

이제 박실장의 캐릭터는 어느 정도 완성됐습니다.

문제는 아직 실제 Calendar가 없다는 겁니다.

6. Google Calendar 연결하기

OpenClaw에는 Google Workspace를 다루는 gog skill이 bundled 되어 있습니다.

Calendar뿐 아니라 Gmail, Drive, Contacts 등도 다룰 수 있는 CLI입니다.

그런데 확인해보니:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  skills info gog --agent calendar

결과가:

gog Disabled

Requirements:
  Binaries: ✗ gog

였습니다.

Skill 정의는 OpenClaw 안에 있는데 정작 실행 파일인 gog가 Docker image에 없습니다.

그래서 image에 직접 넣기로 했습니다.

7. 첫 번째 대삽질 - OpenClaw 버전이 내려가버렸다

처음에는 기존 OpenClaw Dockerfile에 gog 설치 부분을 추가하고 그냥 build했습니다.

그런데 Gateway가 계속 재시작합니다.

docker compose ps

로그를 확인해보니:

Your OpenClaw config was written by version 2026.8.2,
but this command is running 2026.8.1.

Refusing to run automatic gateway startup migrations...

엥?

원인은 이거였습니다.

기존 실행 image
OpenClaw 2026.8.2
       ↓
로컬 Dockerfile build
       ↓
내가 checkout 해둔 source는 2026.8.1
       ↓
2026.8.1 image 생성
       ↓
config는 이미 2026.8.2가 작성함
       ↓
구버전 binary가 신버전 config를 읽으려고 함
       ↓
Gateway: 응 안돼

OpenClaw가 오히려 구버전 binary로 config를 망가뜨리지 않도록 막아준 셈입니다.

여기서:

OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1

같은 옵션으로 억지로 내려가는 방법도 있었지만, 제가 원하는 건 downgrade가 아니므로 사용하지 않았습니다.

공식 image를 다시 pull해서 복구했습니다.

cd /home/fcsd/openclaw

docker compose stop openclaw-gateway

docker pull ghcr.io/openclaw/openclaw:latest

docker compose up -d --force-recreate --no-build openclaw-gateway

버전 확인:

docker compose exec openclaw-gateway \
  node dist/index.js --version

결과:

OpenClaw 2026.8.2 (0965053)

살았습니다.

8. 기존 Dockerfile을 건드리지 말고 확장 image 만들기

교훈을 얻었습니다.

gog 하나 넣겠다고 OpenClaw source image를 다시 build하지 말자.

그래서 별도의 Dockerfile.gog를 만들었습니다.

FROM ghcr.io/openclaw/openclaw:latest

USER root

ARG GOG_VERSION="0.38.2"

RUN set -eux; \
    curl -fsSL \
      "https://github.com/openclaw/gogcli/releases/download/v${GOG_VERSION}/gogcli_${GOG_VERSION}_linux_amd64.tar.gz" \
      -o /tmp/gogcli.tar.gz; \
    tar -xzf /tmp/gogcli.tar.gz -C /tmp; \
    install -m 0755 /tmp/gog /usr/local/bin/gog; \
    rm -f /tmp/gogcli.tar.gz /tmp/gog; \
    gog --version

RUN chmod 1777 /tmp

USER node

Compose의:

build: .

도 다음처럼 변경했습니다.

build:
  context: .
  dockerfile: Dockerfile.gog

이제 구조는:

공식 OpenClaw image
       ↓
Dockerfile.gog
       ↓
gog만 추가
       ↓
내 OpenClaw image

훨씬 깔끔합니다.

9. 두 번째 대삽질 - /tmp 권한 때문에 Gateway 무한 재시작

새 image를 만들고 Gateway를 띄웠습니다.

docker compose up -d --force-recreate openclaw-gateway

그런데 또 restart loop.

ㅋㅋ

로그를 확인했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  logs --tail=100 openclaw-gateway

이번에는:

Unable to create fallback OpenClaw temp dir: /tmp/openclaw-1000

권한을 확인해봤습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm --no-deps \
  --entrypoint sh \
  openclaw-gateway \
  -lc 'id; ls -ld /tmp; touch /tmp/test-file && echo tmp-writable; mkdir -p /tmp/openclaw-1000 && ls -ld /tmp/openclaw-1000'

결과:

uid=1000(node) gid=1000(node)
drwxr-xr-x ... /tmp

touch: cannot touch '/tmp/test-file': Permission denied
mkdir: cannot create directory '/tmp/openclaw-1000': Permission denied

찾았습니다.

정상적인 /tmp는 보통:

drwxrwxrwt

즉 1777이어야 합니다.

그래서 Dockerfile.gog에:

RUN chmod 1777 /tmp

를 추가했습니다.

다시 build하고 확인했습니다.

docker compose exec openclaw-gateway \
  sh -lc 'ls -ld /tmp; touch /tmp/test-file && echo tmp-ok'

결과:

drwxrwxrwt ... /tmp
tmp-ok

그리고:

docker compose exec openclaw-gateway \
  node dist/index.js --version

OpenClaw 2026.8.2 (0965053)

gog도:

docker compose exec openclaw-gateway \
  gog --version

v0.38.2

오케이 진짜 굿.

10. Google OAuth Client 만들기

이제 Google Calendar와 실제로 연결해야 합니다.

Google Cloud에서 프로젝트를 만들고 OAuth 설정을 했습니다.

필요한 것은:

Google Cloud Project
       ↓
Google Auth Platform
       ↓
OAuth Client
       ↓
Desktop App
       ↓
client_secret.json

그리고 Google Calendar API도 활성화해야 합니다.

이걸 빼먹으면 나중에 아주 친절하게 403을 맞습니다.

다운로드한 client_secret.json은 서버의 별도 디렉토리에 저장했습니다.

/home/fcsd/openclaw/googleSecret/client_secret.json

당연히 이 파일도 Git에 올리면 안 됩니다.

11. Docker 안에서는 호스트 경로가 안 보인다

처음에는 아무 생각 없이:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  gog auth credentials /home/fcsd/openclaw/googleSecret/client_secret.json

을 실행했습니다.

결과:

no such file or directory

파일이 있는데?

ls -l

client_secret.json

당연한 이야기지만 docker compose exec 이후 명령은 컨테이너 내부에서 실행됩니다.

즉:

Host
/home/fcsd/openclaw/googleSecret/client_secret.json
       │
       X mount 안 됨
       │
Container
/home/fcsd/openclaw/googleSecret/client_secret.json
→ 없음

그래서 임시로 container에 복사했습니다.

docker cp \
  /home/fcsd/openclaw/googleSecret/client_secret.json \
  openclaw-openclaw-gateway-1:/tmp/client_secret.json

그리고:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  gog auth credentials /tmp/client_secret.json

성공했습니다.

client  default
client_secret_in_keyring  true

12. Google OAuth 403 - Test user를 등록해야 한다

이제 Google 계정을 연결했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec -it openclaw-gateway \
  gog auth add  \
  --services calendar \
  --manual

홈 서버에는 브라우저가 없으니 --manual을 사용합니다.

터미널에 출력되는 Google 로그인 URL을 내 PC에서 열었는데...

액세스 차단됨

앱은 현재 테스트 중이며
개발자가 승인한 테스터만 앱에 액세스할 수 있습니다.

403 오류: access_denied

또 시작이군요.

원인은 OAuth 앱이 Testing 상태인데 로그인하려는 Google 계정을 Test user로 등록하지 않았기 때문이었습니다.

Google Cloud에서:

Google Auth Platform
→ Audience
→ Test users
→ 내 Google 계정 추가

후 다시 인증했습니다.

이번에는 성공했습니다.

email     
services  calendar
client    default

13. Google Calendar API를 안 켜면 또 403

OAuth까지 성공했으니 신나게 조회했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec -it openclaw-gateway \
  gog calendar events --today

그런데:

Google API error (403 accessNotConfigured):
Google Calendar API ... is disabled.

OAuth 권한을 받았다고 Calendar API가 자동으로 활성화되는 것은 아니었습니다.

Google Cloud에서:

APIs & Services
→ Library
→ Google Calendar API
→ Enable

활성화했습니다.

잠깐 기다렸다가 다시:

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec -it openclaw-gateway \
  gog calendar events --today

결과:

No events

짜라란~

No events가 이렇게 반가울 줄이야.

14. 그런데 passphrase를 사람이 입력하면 AI 비서가 아니잖아?

gog는 keyring을 사용할 때 계속:

Enter passphrase to unlock ...

를 요구했습니다.

제가 직접 터미널에서 사용할 거라면 상관없지만 박실장은 Discord 요청을 받고 알아서 Calendar를 조회해야 합니다.

따라서 사람이 passphrase를 입력하는 구조면 안 됩니다.

.env에 다음 환경변수를 설정했습니다.

GOG_KEYRING_BACKEND=file
GOG_KEYRING_PASSWORD=
GOG_ACCOUNT=

실제 비밀번호는 당연히 공개하지 않습니다.

그리고 gog 인증 정보가 Docker container recreate 때 사라지지 않도록 영속 경로도 잡았습니다.

GOG_HOME=/home/node/.openclaw/gogcli

최종적으로는:

GOG_HOME=/home/node/.openclaw/gogcli
GOG_KEYRING_BACKEND=file
GOG_KEYRING_PASSWORD=...
GOG_ACCOUNT=...

형태입니다.

/home/node/.openclaw은 이미 OpenClaw에서 persistent하게 사용하고 있으므로 여기에 gog 데이터를 두면 container를 다시 만들어도 인증 정보를 유지할 수 있습니다.

그 후에는:

docker compose exec openclaw-gateway \
  gog calendar events --today

를 실행해도 passphrase 입력 없이:

No events

가 바로 나옵니다.

이제 진짜 자동화가 가능합니다.

15. 마지막 함정 - gog가 설치됐는데 박실장은 모른다

이제 Discord에서 박실장에게 말했습니다.

@박실장 오늘 일정 확인해줘

그런데 박실장 왈:

현재 이 일정관리실에는 캘린더 조회 연결이 아직 없어
오늘 일정을 확인할 수 없습니다.

???

터미널에서는 분명히:

gog calendar events --today

가 잘 되는데 박실장은 Calendar가 없다고 합니다.

Skill 상태를 다시 확인했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  skills info gog --agent calendar

결과:

🎮 gog Disabled

Visible to model: no
Available as command: no

Requirements:
  Binaries: ✓ gog

여기가 핵심이었습니다.

Binaries: ✓ gog

는 단순히 gog 실행 파일이 존재한다는 뜻입니다.

하지만:

Visible to model: no

이면 박실장 모델 입장에서는 gog라는 도구 자체가 없는 것이나 마찬가지입니다.

그래서 박실장에게 gog skill을 허용했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set agents.entries.calendar.skills \
  '["gog"]' \
  --strict-json

그리고 gog skill도 활성화했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  config set skills.entries.gog.enabled \
  true \
  --strict-json

Gateway를 재시작했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  restart openclaw-gateway

다시 확인하면 모델에서 gog를 사용할 수 있는 상태가 됩니다.

그리고 Discord에서 다시:

@박실장 오늘 일정 확인해줘

테스트했습니다.

드디어 성공했습니다.

16. 최종 구조

여기까지 완성된 구조를 정리하면 이렇습니다.

                         👤 나
                           │
                           │ Discord
                           ▼
                    📅 @박실장 Bot
                           │
                           │ accountId: calendar
                           ▼
                 OpenClaw calendar agent
                           │
                    GPT-5.6 Terra
                           │
                           │ gog skill
                           ▼
                      gog CLI
                           │
                           │ OAuth 2.0
                           ▼
                  Google Calendar API
                           │
                           ▼
                    Google Calendar

그리고 김비서는 별도로 존재합니다.

Discord
 │
 ├─ 📎 @김비서
 │      ↓
 │   main agent
 │   GPT-5.6 Sol
 │
 └─ 📅 @박실장
        ↓
     calendar agent
     GPT-5.6 Terra
        ↓
       gog
        ↓
  Google Calendar

이게 제가 처음 원했던 여러 명의 전문 AI 직원이 한 홈 서버에서 돌아가는 구조의 시작입니다.

17. 이번 삽질에서 배운 것

이번 작업은 겉으로 보면 그냥:

OpenClaw에 Google Calendar 연결

인데 실제로는 꽤 여러 레이어를 건드렸습니다.

Discord Bot
    ↓
OpenClaw account routing
    ↓
Agent
    ↓
Skill
    ↓
CLI binary
    ↓
Docker filesystem / permission
    ↓
OAuth
    ↓
Google API

특히 기억할 만한 건 이 정도입니다.

OpenClaw source Dockerfile을 함부로 다시 build하지 말자

실행 중인 버전과 로컬 source 버전이 다르면 저처럼:

config = 2026.8.2
binary = 2026.8.1

상태가 될 수 있습니다.

외부 binary 하나 추가하는 목적이라면 공식 image를 base로 한 별도 확장 Dockerfile이 훨씬 안전했습니다.

Docker의 /tmp 권한도 중요하다

OpenClaw은 /tmp/openclaw-1000 같은 임시 디렉토리를 만듭니다.

/tmp = 755

이면 non-root node 사용자가 쓰지 못해서 Gateway가 죽을 수 있습니다.

정상적으로:

/tmp = 1777

인지 확인해야 합니다.

OAuth 성공과 API 사용 가능은 다른 문제다

OAuth 인증 성공
≠
Google Calendar API 활성화

Calendar API를 별도로 Enable해야 했습니다.

Binary 설치와 Skill 노출도 다른 문제다

이게 이번에 제일 재밌었습니다.

Binaries: ✓ gog
Visible to model: no

라면 사람은 gog를 실행할 수 있지만 AI Agent는 존재 자체를 모릅니다.

결국 AI agent에게 실제 능력을 붙이려면:

Binary
+
Authentication
+
Skill enable
+
Agent allowlist

가 전부 맞아야 합니다.

18. 이제 다음은?

1편에서는 김비서 한 명으로 끝났지만, 이제 2편에서 박실장까지 실제 Google Calendar를 사용할 수 있게 됐습니다.

앞으로는 이런 식으로 사용하고 싶습니다.

나:
내일 오후 3시에 치과 일정 잡아줘

박실장:
내일 15:00에 '치과' 일정 등록했습니다.

또는:

나: 이번 주 언제 시간 비어?

박실장:
화요일 14:00~17:00,
목요일 오전이 비교적 여유롭습니다.

그리고 장기적으로는:

                      📎 김비서
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
       📅 박실장        📈 한팀장        🖥️ 최과장
     Google Calendar     Market          Server

까지 만들어볼 생각입니다.

이제 구조가 진짜 조금씩 AI 비서 조직처럼 보이기 시작합니다.

1편
└─ 📎 김비서 출근

2편
└─ 📅 박실장 출근 + Google Calendar 연결 완료

박실장은 이제 출근 완료입니다.

다음 편부터는 이 직원들이 대화를 기억할 수 있도록 Memory 쪽을 손봐볼 생각입니다.

오케이 굿.

홈 서버 구축기 - OpenClaw 개인 AI 비서 만들기 🦞

Thu, 03 Sep 2026 15:13:38 GMT

때는 2026년 1월 9일..

저렴한 가격에 홈 서버를 구매/설치 해놓고 사실 그동안 제대로 활용하지 못하고 있었습니다.

매일 아침 10시에 코인마켓캡 Fear&Greed 지표를 보내주는 봇을 돌리는 서버 정도로만 사용하고 있었죠..

요즘 어딜가도 AI, Agent 등 이야기가 나오고 있고 개인적으로도 관심이 많이 생겨서

"그럼 그냥 내 홈 서버에 24시간 돌아가는 개인 AI 비서를 하나 만들어보자."

라는 생각이 들었습니다.

(사실 예전에 오픈클로를 한번 셋업해보긴 했지만 성능이슈로 버렸습니다)

시간도 꽤 지났고, Openclaw 2.0이 출시되었다는 소식!! (실제 2.0은 아니고 자잘한 버그 고치다 보니 여기저기 건든곳이 많아서 이정도면 버전2 아니야? 라는 네이밍이라고는 합니다 ) 그 소식과 AI 성능도 이전에 비하면 훨씬 향상되었기 때문에, OpenClaw를 홈서버에 올려보기로 했습니다.

최종적으로 만들고 싶은 구조는 대충 이런 느낌입니다.

Discord
   ↓
OpenClaw Gateway
   ↓
Agent
   ↓
OpenAI GPT
   ↓
Web Search / Tools / Memory ...

일단 이번 글에서는

Docker로 OpenClaw Gateway를 띄우고 → OpenAI를 연결하고 → Discord에서 대화할 수 있는 상태까지

만들어보겠습니다.

그리고 역시나 한 번에 되지는 않았습니다.

1. Docker부터 설치

OpenClaw를 서버에 직접 설치할 수도 있지만 저는 가능하면 홈 서버에 이것저것 설치해서 환경을 더럽히고 싶지 않았습니다.

또 나중에 OpenClaw를 지우거나 버전을 바꾸기도 편할 것 같아서 Docker로 구성하기로 했습니다.

그런데...

docker --version

Docker부터 없었습니다.

Docker 공식 저장소를 추가해서 설치해줍니다.

sudo apt update
sudo apt install -y ca-certificates curl

Docker 저장소의 GPG key를 등록합니다.

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc

Docker apt repository를 추가합니다.

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

패키지 목록을 다시 읽고 Docker를 설치합니다.

sudo apt update

sudo apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

설치 확인.

docker --version
docker compose version

이렇게 Docker는 설치됐습니다.

2. 매번 sudo 붙이지 않게 docker group 추가

Docker 명령어를 실행할 때마다 sudo를 붙이는 건 귀찮습니다.

그래서 현재 사용자를 docker 그룹에 추가했습니다.

sudo usermod -aG docker $USER

여기서 옵션은

-a : 기존 그룹은 유지하면서 append
-G : supplementary group 지정

이라는 뜻입니다.

즉 현재 사용자를 기존 그룹에서 빼지 않고 docker 그룹에도 추가합니다.

적용하려면 로그아웃 후 다시 로그인해야 합니다.

다시 접속한 다음

docker ps

를 실행해서 sudo 없이 정상적으로 동작하는지 확인했습니다.

참고로 docker 그룹은 사실상 root에 가까운 권한을 가질 수 있으므로 아무 서버에서나 막 추가하는 건 좋지 않습니다. 제 경우 개인 홈 서버라 편의성을 위해 이렇게 구성했습니다.

💡 docker 그룹은 무엇인가?

Linux에는 사용자마다 소속 그룹(group)이라는 개념이 있습니다.

예를 들어 현재 사용자가 어떤 그룹에 속해 있는지 확인하려면:

groups

를 사용할 수 있습니다.

Docker를 설치하면 일반적으로 docker라는 그룹이 만들어지고, 이 그룹에 속한 사용자는 Docker socket에 접근할 수 있습니다.

그래서:

sudo usermod -aG docker $USER

를 실행합니다.

각 부분을 뜯어보면:

sudo
└── 관리자 권한으로 실행

usermod
└── 사용자 계정 정보를 수정

-a
└── append
    기존 supplementary group을 유지

-G docker
└── docker 그룹을 supplementary group으로 추가

$USER
└── 현재 로그인한 사용자

즉 한마디로:

“현재 사용자를 기존 그룹에서 빼지 말고 docker 그룹에도 추가해줘.”

라는 뜻입니다.

특히 -a가 중요합니다.

실수로:

sudo usermod -G docker $USER

처럼 -a 없이 사용하면 기존 supplementary group 목록을 의도치 않게 변경할 수 있으므로 주의해야 합니다.

3. OpenClaw 설치

이제 본론입니다.

OpenClaw 저장소를 clone 합니다.

cd ~

git clone https://github.com/openclaw/openclaw.git

cd openclaw

OpenClaw는 Docker 이미지를 직접 build할 수도 있는데, 홈 서버에서 굳이 소스 전체를 build하지 않고 공식 pre-built image를 사용했습니다.

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

그리고 setup script 실행.

./scripts/docker/setup.sh

이 스크립트가 생각보다 많은 일을 해줍니다.

대충

Docker image 준비
      ↓
OpenClaw onboarding
      ↓
Gateway 설정
      ↓
Agent workspace 생성
      ↓
인증 설정
      ↓
Docker Compose Gateway 실행

까지 이어집니다.

4. OpenClaw 초기 설정

setup script를 실행하면 터미널에서 onboarding이 시작됩니다.

처음에는 보안 관련 안내가 나옵니다.

OpenClaw Agent는 단순 챗봇이 아니라 파일이나 Shell 같은 실제 시스템 도구에 접근할 수 있기 때문에 이런 경고가 나오는 것 같습니다.

개인 홈 서버에서 제가 직접 사용하는 환경이므로 내용을 확인하고 진행했습니다.

Telemetry는 굳이 필요하지 않아서

No thanks

를 선택했습니다.

Setup mode는

QuickStart

를 선택했습니다.

5. Gateway 설정

QuickStart에서 Gateway 기본값은 다음과 같이 잡았습니다.

Gateway port : 18789
Gateway auth : Token
Tailscale    : Off

첫 번째 Agent 이름은 그냥 기본값인

main

을 사용했습니다.

나중에는

main
dev
research

처럼 Agent를 나눠서 Discord 채널별로 연결해볼 생각입니다.

OpenClaw의 재미있는 점이 단순히 AI 하나를 실행하는 게 아니라 하나의 Gateway 아래에 여러 Agent를 구성할 수 있다는 점입니다.

6. OpenAI 연결

모델 Provider는 OpenAI를 선택했습니다.

API Key를 별도로 발급해서 사용하는 방식도 있지만 저는 기존 ChatGPT/Codex 계정을 이용하는 OAuth 방식을 사용했습니다.

ChatGPT Login

을 선택했고, 다음과 같은 메세지가 나왔습니다

https://auth.openai.com/oauth/authorize?response_type=code&client_id=app_~~

제 홈 서버 환경은 CLI 환경이었기 때문에, OAuth URL을 복사하여 제 PC 에서 따로 접속을 했습니다.

URL을 통해 OpenAI 로그인을 했는데,

?

당황했습니다.

알고보니 저 리다이렉트 된 주소 http://localhost:1455/auth/callback~~~ 를 전체 복사하여 CLI 환경에 붙여넣기 하라고 하더군요.. (한국인 특 : 설명서 안읽음)

기본 모델은 설치 과정에서

openai/gpt-5.6-sol

로 일단 설정을 했고,

모델 선택 화면에서는 그대로

Keep current

를 선택했습니다.

그 다음 실제 completion을 한번 날려서 인증과 모델 접근이 정상인지 테스트하는 화면이 나옵니다.

Test AI access now with a live completion?

Yes

실제 요청 하나까지 성공하는 걸 확인했습니다.

7. Discord를 OpenClaw의 메신저로 사용하기

홈 서버에 SSH 접속을 해서 OpenClaw에게 말을 거는것은 너무나도 귀찮은 일이기 때문에 메신저를 활용하려고 했고, Discord를 선택했습니다.

(discord 관련 패키지를 설치할까요?에서 계속 no 를 선택했던 뻘짓이 남아있네요)

Discord (Bot API)

디스코드 봇 토큰을 발급하는 방법도 알려주네요.

제 Bot token을 입력해 주었고 전체 채널에서 동작하게 하는 건 싫어서 접근 정책은

Allowlist

로 설정했습니다.

OpenClaw에서는 Discord 서버와 채널을 다음과 같이 지정할 수 있습니다.

guildId/channelId

Discord에서 개발자 모드를 켜면 서버 ID와 채널 ID를 복사할 수 있습니다.

저는 개인 Discord 서버의 사장실이라는 채널 하나만 허용했습니다.

구조는 대충 이런 느낌입니다.

Discord Server
│
├── 일반 채널
│      └── OpenClaw 접근 X
│
└── #사장실
       └── OpenClaw 접근 O

실제 config에는 다음과 비슷하게 들어갑니다.

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "",
      "groupPolicy": "allowlist",
      "guilds": {
        "": {
          "channels": {
            "": {
              "enabled": true
            }
          }
        }
      }
    }
  }
}

당연하지만 Discord Bot Token은 비밀번호나 마찬가지이므로 GitHub에 올리거나 블로그에 노출하면 안 됩니다.

8. "Gateway not detected"...?

온보딩 마지막쯤 이런 메시지가 나왔습니다.

Systemd user services are not available inside this container.

Gateway not detected yet.

Start now:
openclaw gateway run

순간

"엥? 설치 실패했나?"

했는데 Docker 환경이라 그런 것이었습니다.

컨테이너 안에서는 systemd user service를 설치하는 방식이 아니라 Docker Compose가 Gateway 프로세스를 관리합니다.

setup script가 끝까지 실행되고 나니

Starting gateway

Container openclaw-openclaw-gateway-1 Started
Container openclaw-openclaw-gateway-1 Running

으로 정상 실행됐습니다.

설정 위치도 출력됩니다.

Config: /home/fcsd/.openclaw
Workspace: /home/fcsd/.openclaw/workspace

9. Gateway Health Check

설치가 끝났으니 Gateway가 실제로 살아있는지 확인했습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

docker compose exec : 현재 실행 중인 container 안에서 명령 실행
openclaw-gateway : 명령을 실행할 서비스
gateway health : Gateway health check
OPENCLAW_GATEWAY_TOKEN : Gateway 인증에 사용하는 token

결과는

Gateway Health
OK (5ms)
Discord: blocked

Gateway는 정상인데...

Discord가 blocked?

여기서 첫 번째 삽질이 시작됩니다.

10. Discord Bot Token 등록

온보딩에서 Discord와 allowlist까지 설정했지만 Bot Token 연결도 확인해주었습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels add \
  --channel discord \
  --token ''

에는 Discord Developer Portal에서 발급받은 실제 Bot Token을 넣으면 됩니다.

docker compose run --rm은 OpenClaw CLI용 일회성 container를 실행하고 명령이 끝나면 container를 제거합니다.

등록 결과:

Added Discord account "default".

채널 목록도 확인합니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels list

결과:

Chat channels:
- Discord default: installed, configured, enabled

오?

그럼 된 건가?

다시 Health Check.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

그런데 여전히

Discord: blocked

...

11. `channels status --probe`로 원인 찾기

단순히 channels list만 봐서는 왜 막혀있는지 알 수 없었습니다.

그래서 실제 Gateway와 Discord 연결 상태까지 확인해봤습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels status --probe

결과:

Gateway reachable.
- Discord default:
  enabled,
  configured,
  error: Gateway websocket closed: 4014,
  running,
  disconnected,
  bot:@김비서,
  intents:content=disabled,
  health:blocked,
  works,
  audit ok

여기서 범인이 거의 보입니다.

Gateway websocket closed: 4014
intents:content=disabled

그래도 정확한 원인을 확인하기 위해 Gateway 로그도 봤습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  logs --tail=200 openclaw-gateway

--tail=200은 Gateway 로그의 마지막 200줄만 출력합니다.

그리고 로그에서 아주 친절하게 알려줍니다.

Discord Message Content Intent is disabled;
bot may not respond to channel messages.

gateway websocket closed code=4014
reason=Disallowed intent(s).

missing privileged gateway intents.

아하!

OpenClaw 문제가 아니라 Discord Bot 설정 문제였습니다.

12. Discord Message Content Intent

Discord Developer Portal에서 Bot 설정으로 이동했습니다.

Discord Developer Portal
        ↓
Application
        ↓
Bot
        ↓
Privileged Gateway Intents
        ↓
MESSAGE CONTENT INTENT

MESSAGE CONTENT INTENT를 ON으로 변경했습니다.

저는 추후 사용자/Role 기반 제어도 해볼 수 있어서 SERVER MEMBERS INTENT도 같이 켜두었습니다.

설정을 바꿨으니 Gateway를 재시작합니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  restart openclaw-gateway

그리고 바로 probe를 날렸는데...

Gateway not reachable at ws://127.0.0.1:18789
ECONNREFUSED

ㅋㅋ

또 안됩니다.

13. 이번엔 ECONNREFUSED?

이번 문제는 별거 아니었습니다.

Gateway를 restart한 직후 바로 probe를 실행해서 아직 Gateway가 18789 포트를 열기도 전에 CLI가 접속을 시도한 것이었습니다.

잠깐 기다린 뒤 다시 Health Check.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

이번에는

Gateway Health
OK (5ms)
Discord: configured

오케이 굿.

그리고 다시 Discord probe.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels status --probe

최종 결과:

Gateway reachable.
- Discord default:
  enabled,
  configured,
  running,
  connected,
  bot:@김비서,
  token:***,
  intents:content=limited,
  works,
  audit ok

드디어

running
connected
works
audit ok

가 떴습니다.

짜라란~

14. 현재 구조

여기까지 구성하고 나면 제 홈 서버는 대충 다음과 같은 구조가 됩니다.

Discord
  │
  │  #사장실
  ▼
@김비서
  │
  ▼
OpenClaw Gateway
  │
  ├── main Agent
  │
  ├── OpenAI OAuth
  │      └── openai/gpt-5.6-sol
  │
  ├── Codex Hosted Search
  │
  └── Workspace / Memory / Sessions

기존에는

홈 서버
   ↓
매일 아침
   ↓
CoinMarketCap Fear & Greed
   ↓
Telegram 전송

정도로만 사용하고 있었는데 이제는 24시간 켜져 있는 서버에 실제 AI Agent가 하나 들어왔습니다.

이제 좀 홈 서버 산 보람이 생기는 것 같습니다.

15. 자주 사용할 것 같은 명령어 정리

OpenClaw를 Docker로 운영하면서 자주 사용할 것 같은 명령어도 정리해두겠습니다.

Container 상태 확인

docker compose -f /home/fcsd/openclaw/docker-compose.yml ps

현재 Gateway container가 정상적으로 실행 중인지 확인합니다.

Gateway 로그 확인

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  logs -f openclaw-gateway

-f 옵션을 사용하면 실시간으로 로그를 따라갑니다.

최근 로그만 보고 싶다면

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  logs --tail=200 openclaw-gateway

Gateway 재시작

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  restart openclaw-gateway

설정 변경 후 Gateway를 재시작할 때 사용합니다.

단, .env나 Compose environment 자체를 변경했다면 단순 restart가 아니라 container를 recreate해야 변경된 환경변수가 반영될 수 있습니다.

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  up -d openclaw-gateway

Gateway Health Check

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  exec openclaw-gateway \
  sh -lc 'node dist/index.js gateway health --token "$OPENCLAW_GATEWAY_TOKEN"'

Gateway와 Channel의 기본 Health 상태를 확인합니다.

Discord 상태 확인

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels status --probe

Discord가 실제로 연결되어 있는지 확인할 때 굉장히 유용했습니다.

Channel 목록

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels list

현재 등록된 Channel을 확인합니다.

Discord 추가

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  channels add \
  --channel discord \
  --token ''

Discord Bot Token을 등록합니다.

OpenClaw Doctor

설치 도중 다음과 같은 메시지도 한번 확인했습니다.

OpenClaw config identity changed while persisting the refreshed plugin registry
Run "openclaw doctor --fix"

이런 config/migration 관련 문제를 정리할 때는

docker compose -f /home/fcsd/openclaw/docker-compose.yml \
  run --rm openclaw-cli \
  doctor --fix

를 사용할 수 있습니다.

마치며

처음에는

"Docker 하나 띄우고 OpenAI 연결하면 끝나는 거 아닌가?"

라고 생각했는데 역시 이런 건 한 번에 되는 법이 없습니다.

특히 이번에 삽질했던 부분은

Discord: blocked
      ↓
Bot Token 문제인가?
      ↓
Allowlist 문제인가?
      ↓
channels status --probe
      ↓
4014 Disallowed intent(s)
      ↓
Message Content Intent 발견
      ↓
Gateway restart
      ↓
ECONNREFUSED
      ↓
아 그냥 아직 재시작 중이었구나...
      ↓
connected

였습니다.

그래도 OpenClaw CLI에서 상태와 로그를 꽤 자세하게 보여줘서 원인 찾는 것 자체는 어렵지 않았습니다.

현재는 main Agent 하나만 만들어놓은 상태인데 다음에는 여기서 조금 더 욕심을 내서

Discord
│
├── #사장실
│      └── main
│
├── #개발실
│      └── dev
│
└── #자료조사실
       └── research

처럼 하나의 OpenClaw Gateway에 여러 Agent를 만들고 Discord 채널별로 Agent를 분리해볼 생각입니다.

그리고 dev Agent에는 개발에 필요한 Tool을 붙이고, research Agent에는 Web Search와 자료조사에 필요한 Tool을 붙여서 각자 역할을 나눠보려고 합니다.

단순히 ChatGPT를 Discord에서 사용하는 것과 달리,

내 서버에서 24시간 살아있고, 각자 Workspace와 Memory를 가지고, 실제 Tool을 사용할 수 있는 Agent를 만드는 것.

이게 OpenClaw를 설치해보고 싶었던 가장 큰 이유였습니다.

일단 오늘은 여기까지.

다음엔 진짜 비서처럼 부려먹어보겠습니다.

EC2에 내 서버를 올리고 HTTPS로 서비스하기

Tue, 01 Sep 2026 05:18:11 GMT

부제 : DNS, Nginx, Reverse Proxy, SSL/TLS 이해하기

바이브코딩 및 AI 를 활용할 때 개인적으로 항상 개념숙지 -> 구현 순으로 진행합니다. 개념숙지가 안된상태로 구현을 하게 되면 찝찝함이 많이 남는 편이라 그렇습니다. 아래 내용은 개념 숙지를 위해 관련된 내용을 AI에게 정리시킨 내용입니다.

백엔드 서버를 하나 만들었다고 해보자.

Node.js든 Fastify든 Spring이든 서버를 실행하면 보통 다음과 같은 형태로 동작한다.

http://localhost:3000

개발할 때는 이것만으로 충분하다.

하지만 실제 인터넷에서

https://mock-exchange.example.com

같은 주소로 서비스를 제공하려면 몇 가지 요소가 추가로 필요하다.

전체 구조부터 보면 생각보다 단순하다.

사용자
  │
  │ https://mock-exchange.example.com
  ▼
DNS
  │
  │ "이 도메인의 서버 IP는 1.2.3.4입니다"
  ▼
EC2
  │
  │ :443
  ▼
Nginx
  │
  │ http://127.0.0.1:3000
  ▼
내 백엔드 서버

여기에는 크게 네 가지 개념이 등장한다.

DNS → HTTP/HTTPS → SSL/TLS 인증서 → Nginx Reverse Proxy

하나씩 이해해보자.

1. 가장 먼저 HTTP가 무엇인가?

HTTP는 클라이언트와 서버가 데이터를 주고받는 규칙이다.

예를 들어 브라우저나 다른 서버가 다음 요청을 보냈다고 하자.

GET /api/orderbook
Host: mock-exchange.example.com

서버에서는:

{
  "bids": [],
  "asks": []
}

같은 응답을 반환한다.

이게 기본적인 HTTP 통신이다.

구조를 단순화하면:

Client
   │
   │ HTTP Request
   ▼
Server
   │
   │ HTTP Response
   ▼
Client

HTTP의 기본 포트는 80이다.

따라서:

http://mock-exchange.example.com

은 기본적으로:

mock-exchange.example.com:80

으로 접속한다.

2. HTTP의 문제점

HTTP 자체에는 암호화가 없다.

예를 들어 클라이언트가 서버에 다음 데이터를 보낸다고 생각해보자.

{
  "email": "user@example.com",
  "password": "12345678"
}

HTTP만 사용한다면 네트워크를 통과하는 데이터가 암호화되지 않는다.

그래서 중간에서 트래픽을 관찰할 수 있는 공격자가 데이터를 읽거나 변조할 가능성이 생긴다.

이 문제를 해결하기 위해 HTTP에 TLS를 적용한 것이 HTTPS다.

TLS는 통신에 크게 세 가지 보안 속성을 제공한다.

Encryption(암호화) — 중간에서 내용을 읽기 어렵게 한다.
Integrity(무결성) — 전송 중 데이터가 몰래 변조되는 것을 탐지한다.
Authentication(인증) — 접속한 서버가 실제 해당 도메인의 서버인지 검증한다. (MDN Web Docs)

3. HTTPS란?

HTTPS는 완전히 별개의 웹 프로토콜이라고 생각하기보다,

HTTP
+
TLS

라고 이해하면 쉽다.

즉:

HTTP
────────────────
평문 HTTP 통신
HTTPS
────────────────
HTTP
  ↓
TLS 암호화
  ↓
TCP

HTTPS의 기본 포트는 443이다.

그래서:

https://mock-exchange.example.com

이라고 하면 브라우저는 기본적으로:

mock-exchange.example.com:443

에 연결한다. (MDN Web Docs)

4. SSL과 TLS는 뭐가 다른가?

서버를 운영하다 보면 이런 표현을 매우 자주 본다.

SSL 인증서
SSL 설정
SSL certificate
HTTPS SSL

하지만 현대 웹에서 실제로 사용하는 기술은 TLS다.

SSL은 TLS의 전신이다.

대략:

SSL 2.0
   ↓
SSL 3.0
   ↓
TLS 1.0
   ↓
TLS 1.1
   ↓
TLS 1.2
   ↓
TLS 1.3

으로 발전했다.

현재 웹에서는 TLS 1.2와 TLS 1.3을 사용하며, SSL 및 오래된 TLS 버전은 사용하지 않는 것이 일반적이다. (MDN Web Docs)

그런데 관습적으로 아직도 사람들이:

SSL 인증서

라고 부른다.

따라서 실무에서는 대충:

SSL 인증서 ≒ TLS 인증서

라고 이해해도 된다.

5. 그러면 SSL/TLS 인증서는 왜 필요한가?

여기서 중요한 문제가 하나 있다.

사용자가:

https://mock-exchange.example.com

에 접속했다고 해보자.

암호화를 하기 전에 먼저 확인해야 하는 것이 있다.

“내가 지금 통신하려는 서버가 정말 mock-exchange.example.com 서버가 맞나?”

공격자가 중간에서 자신을 진짜 서버인 것처럼 속이면 암호화 자체가 의미가 없어질 수 있기 때문이다.

그래서 서버는 자신의 신원을 증명하는 TLS Certificate를 제공한다.

인증서에는 해당 도메인과 공개키 등 서버의 신원을 검증하는 데 필요한 정보가 포함된다. 브라우저는 신뢰할 수 있는 인증기관(CA)이 발급한 인증서인지, 접속한 도메인과 인증서가 일치하는지 등을 확인한다. (MDN Web Docs)

CA(Certificate Authority)는 무엇인가?

CA는 인증서를 발급하고 신뢰를 보증하는 기관이다.

예를 들어:

사용자
 │
 │ "이 인증서 믿어도 돼?"
 ▼
브라우저
 │
 │ 신뢰하는 CA가 서명했는지 확인
 ▼
Certificate
 │
 ▼
mock-exchange.example.com

대표적으로 Let’s Encrypt 같은 CA가 있다.

Let’s Encrypt는 무료 TLS 인증서를 제공하는 비영리 인증기관이다. (letsencrypt.org)

실제로 우리가 EC2를 구성할 때 사용할 수 있는 방법이:

Let's Encrypt
      │
      │ 인증서 발급
      ▼
Certbot
      │
      │ Nginx 설정
      ▼
Nginx

이다.

7. Certbot은 뭐지?

여기서 많이 헷갈리는 부분이다.

Let’s Encrypt와 Certbot은 같은 것이 아니다.

쉽게 구분하면:

Let's Encrypt
= 인증서를 발급하는 CA
Certbot
= 인증서 발급/설정/갱신을 자동화해주는 프로그램

예를 들어 서버에서:

sudo certbot --nginx -d mock-exchange.example.com

을 실행하면 Certbot이 Let’s Encrypt를 통해 인증서를 발급받고 Nginx에 적용하는 작업을 상당 부분 자동화할 수 있다.

결과적으로 Nginx가 다음과 같은 인증서 파일을 사용하게 된다.

/etc/letsencrypt/live/mock-exchange.example.com/
├── fullchain.pem
└── privkey.pem

개념적으로:

fullchain.pem
→ 클라이언트에게 보여줄 인증서 + 인증서 체인
privkey.pem
→ 서버의 Private Key

라고 보면 된다.

특히 privkey.pem은 절대 외부에 노출하면 안 된다.

8. 이제 Nginx는 왜 필요한가?

사실 Node.js 서버 자체를 인터넷에 직접 노출할 수도 있다.

예를 들어 Node.js 서버가:

0.0.0.0:3000

으로 실행되고 EC2 Security Group에서 3000을 열어버리면:

http://1.2.3.4:3000

으로 직접 접근할 수 있다.

하지만 실제 서비스에서는 보통 이렇게 하지 않는다.

대신:

Internet
    │
    ▼
Nginx
    │
    ▼
Application

구조를 사용한다.

여기서 Nginx가 Reverse Proxy 역할을 한다.

9. Proxy란?

Proxy라는 개념부터 보면 쉽다.

일반적인 Proxy는 중간에서 요청을 대신 전달하는 서버다.

예를 들어:

나
 │
 ▼
Proxy
 │
 ▼
Google

Google 입장에서는 요청을 Proxy가 보낸 것처럼 보일 수 있다.

이런 구조를 흔히 Forward Proxy라고 한다.

10. Reverse Proxy란?

Reverse Proxy는 반대쪽에 있다.

사용자
 │
 ▼
Reverse Proxy
 │
 ▼
실제 서버

사용자는 실제 Application Server와 직접 통신하지 않는다.

Nginx와 통신한다.

그리고 Nginx가 요청을 실제 Application Server로 전달한다.

NGINX 공식 문서에서도 reverse proxy를 클라이언트 요청을 proxied server에 전달하고, 그 응답을 다시 클라이언트에게 전달하는 구조로 설명한다. (docs.nginx.com)

우리가 만들 구조가 정확히 이것이다.

11. 우리가 만들 EC2 구조

예를 들어 EC2의 Public IP가:

3.35.100.100

이고 Node.js 서버가:

127.0.0.1:3000

에서 실행된다고 해보자.

우리가 원하는 것은:

https://mock-exchange.example.com

으로 요청하면 Node.js의:

http://127.0.0.1:3000

으로 전달되는 것이다.

전체 흐름은:

                 Internet
User
 │
 │ https://mock-exchange.example.com
 │
 ▼
DNS
 │
 │ mock-exchange.example.com
 │            ↓
 │       3.35.100.100
 │
 ▼
EC2
 │
 │ :443
 ▼
┌─────────────────────┐
│        Nginx        │
│                     │
│ HTTPS / TLS 처리     │
│ Reverse Proxy       │
└──────────┬──────────┘
           │
           │ HTTP
           │ 127.0.0.1:3000
           ▼
┌─────────────────────┐
│    Node.js Server   │
│                     │
│   Fastify / Express │
└─────────────────────┘

이 구조가 이번 작업에서 가장 중요하다.

12. 그런데 DNS는 어디에 들어가는가?

도메인은 결국 사람이 읽기 편한 이름이다.

컴퓨터가 실제 서버에 연결하려면 IP 주소가 필요하다.

그래서:

mock-exchange.example.com

을:

3.35.100.100

으로 변환해야 한다.

그 역할을 DNS가 한다.

도메인 관리 서비스에서 A Record를 다음처럼 설정할 수 있다.

Type     Name             Value
A        mock-exchange    3.35.100.100

그러면:

mock-exchange.example.com
        │
        │ DNS Lookup
        ▼
    3.35.100.100

이 된다.

중요한 것은 DNS는 요청을 Node.js로 전달하는 Reverse Proxy가 아니라는 것이다.

DNS가 하는 핵심 역할은:

Domain
   ↓
IP Address

를 알려주는 것이다.

13. DNS → Nginx → Node.js의 관계

따라서 전체 관계를 이렇게 기억하면 된다.

DNS
"어느 서버로 갈까?"
        │
        ▼
EC2 Public IP
Nginx
"이 서버에 들어온 요청을
 어느 Application으로 보낼까?"
        │
        ▼
127.0.0.1:3000
Node.js
"실제 API 로직을 실행"

각자의 역할이 완전히 다르다.

14. Nginx의 server_name

Nginx에는 이런 설정이 들어간다.

server {
    listen 80;
    server_name mock-exchange.example.com;
}

여기서:

listen 80;

은

80번 포트로 들어오는 HTTP 연결을 받겠다.

는 의미다.

그리고:

server_name mock-exchange.example.com;

은

mock-exchange.example.com을 대상으로 들어온 요청은 이 server block에서 처리하겠다.

는 의미다.

이 덕분에 EC2 하나에서 여러 도메인을 운영할 수도 있다.

예를 들어:

EC2
│
│ 3.35.100.100
│
├── api.example.com
│
├── mock-exchange.example.com
│
└── admin.example.com

이 세 도메인이 전부 같은 IP를 가리켜도 Nginx가 요청의 Host를 보고 서로 다른 서버로 전달할 수 있다.

api.example.com
       │
       ▼
127.0.0.1:3000
mock-exchange.example.com
       │
       ▼
127.0.0.1:4000
admin.example.com
       │
       ▼
127.0.0.1:5000

이것이 기존 EC2에 이미 Nginx가 있는데도 새로운 서비스를 추가할 수 있는 이유다.

15. proxy_pass가 핵심이다

Nginx Reverse Proxy 설정에서 가장 중요한 부분은:

location / {
    proxy_pass http://127.0.0.1:3000;
}

이다.

의미는 간단하다.

Nginx로 들어온
/
요청을
127.0.0.1:3000
으로 전달한다.

예를 들어:

GET https://mock-exchange.example.com/api/orderbook

요청이 들어왔다고 하자.

Nginx가 받아서 내부적으로:

GET http://127.0.0.1:3000/api/orderbook

으로 전달한다.

그리고 Node.js 응답을 다시 사용자에게 전달한다. proxy_pass는 NGINX에서 이런 upstream 전달을 지정하는 핵심 directive다. (nginx.org)

따라서 사용자는 Node.js가 3000 포트를 사용하는지 알 필요도 없다.

16. 왜 Node.js를 127.0.0.1에 두는가?

여기에는 보안상의 장점도 있다.

Node.js가:

0.0.0.0:3000

에서 실행되고 Security Group도 3000을 열어놓으면 인터넷에서:

EC2:3000

으로 직접 접근할 가능성이 생긴다.

그러면:

User ───────────────→ Node.js :3000

이라는 Nginx를 우회하는 경로가 존재한다.

반대로 Node.js를:

127.0.0.1:3000

으로만 listen하게 하면 외부에서 직접 접근할 수 없다.

Internet
    │
    X
127.0.0.1:3000

같은 EC2 내부의 Nginx만 접근할 수 있다.

Internet
   │
   ▼
Nginx
   │
   ▼
127.0.0.1:3000

따라서 Security Group도 일반적으로:

80   → Public
443  → Public
3000 → Public에 열지 않음

으로 구성할 수 있다.

17. HTTPS는 어디에서 처리하는가?

여기서 아주 중요한 개념이 하나 나온다.

우리 구조에서는 Node.js가 HTTPS를 직접 처리하지 않는다.

Nginx가 처리한다.

User
 │
 │ HTTPS
 │ encrypted
 ▼
Nginx
 │
 │ HTTP
 │ localhost
 ▼
Node.js

즉 TLS 연결은:

User ↔ Nginx

사이에서 끝난다.

이를 흔히 TLS Termination이라고 한다.

그래서 Node.js 코드는 그냥:

app.listen({
  port: 3000,
  host: "127.0.0.1"
});

처럼 HTTP 서버로 실행해도 된다.

Nginx가:

HTTPS
↓
decrypt
↓
HTTP
↓
Node.js

를 담당한다.

18. Nginx의 HTTPS 설정

개념적으로 HTTPS용 Nginx 설정은 다음과 같다.

server {
    listen 443 ssl;
    server_name mock-exchange.example.com;
    ssl_certificate /etc/letsencrypt/live/mock-exchange.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mock-exchange.example.com/privkey.pem;
    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

여기서:

listen 443 ssl;

은 HTTPS 연결을 받겠다는 뜻이다.

그리고:

ssl_certificate

와:

ssl_certificate_key

가 TLS 연결에 필요한 인증서와 Private Key를 지정한다.

19. HTTP와 HTTPS를 둘 다 열면?

다음처럼 구성할 수도 있다.

HTTP :80
HTTPS :443

하지만 일반적인 웹 서비스에서는 HTTP 요청을 그대로 서비스하기보다 HTTPS로 보내버린다.

예:

server {
    listen 80;
    server_name mock-exchange.example.com;
    return 301 https://$host$request_uri;
}

그러면 사용자가:

http://mock-exchange.example.com/api/orderbook

으로 접속해도 Nginx가:

301 Redirect

를 반환해서:

https://mock-exchange.example.com/api/orderbook

으로 이동시킨다.

HTTPS 사이트가 HTTP 요청을 받아 HTTPS로 redirect하는 것은 일반적인 구성이다. (MDN Web Docs)

따라서 최종 구조는:

HTTP :80
   │
   │ 301 Redirect
   ▼
HTTPS :443
   │
   │ TLS
   ▼
Nginx
   │
   │ Reverse Proxy
   ▼
Node.js :3000

이 된다.

20. proxy_set_header는 왜 필요한가?

실제 설정에서는 보통 다음도 넣는다.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

왜 필요할까?

Reverse Proxy가 있기 때문이다.

원래:

Client
   ↓
Node.js

였다면 Node.js가 직접 클라이언트 정보를 알 수 있다.

하지만 지금은:

Client
   ↓
Nginx
   ↓
Node.js

이다.

Node.js 입장에서는 연결한 상대가 Nginx다.

그래서 Nginx가 원래 요청 정보를 Header에 담아 전달한다. NGINX 공식 문서에서도 proxy_set_header를 이용해 proxied server로 전달하는 Host 등의 헤더를 변경하도록 지원한다. (docs.nginx.com)

대표적으로:

Host
→ 사용자가 요청한 도메인
X-Real-IP
→ 실제 Client IP
X-Forwarded-For
→ Proxy를 거친 Client IP 정보
X-Forwarded-Proto
→ 원래 HTTP인지 HTTPS인지

를 전달한다.

21. AWS Security Group은 어디에 있는가?

여기까지 이해하면 Security Group도 연결된다.

EC2 앞에는 AWS Security Group이라는 방화벽이 있다.

Internet
   │
   ▼
┌─────────────────────┐
│   Security Group    │
│                     │
│ 80  → Allow         │
│ 443 → Allow         │
│ 3000 → Deny         │
└──────────┬──────────┘
           │
           ▼
         EC2
           │
           ▼
         Nginx
           │
           ▼
        Node.js

따라서 이번 서버에서는 보통 외부에:

TCP 80
TCP 443

을 허용하면 된다.

애플리케이션 포트:

3000

은 외부에 열 필요가 없다.

22. 실제 요청 하나를 처음부터 따라가 보자

사용자가 브라우저에:

https://mock-exchange.example.com/api/orderbook

을 입력했다고 하자.

Step 1 — DNS

브라우저가 묻는다.

mock-exchange.example.com의 IP가 뭐야?

DNS가:

3.35.100.100

이라고 알려준다.

Step 2 — TCP 연결

HTTPS이므로:

3.35.100.100:443

으로 연결한다.

Step 3 — TLS Handshake

Nginx가 인증서를 제공한다.

Certificate
Domain:
mock-exchange.example.com
Issuer:
Let's Encrypt

브라우저가 인증서를 검증한다.

TLS handshake 과정에서는 TLS 버전과 암호화 방식 등을 협상하고, 이후 실제 HTTP 데이터가 암호화되어 전달된다. (MDN Web Docs)

Step 4 — HTTPS Request

암호화된 연결이 만들어지면:

GET /api/orderbook
Host: mock-exchange.example.com

요청을 보낸다.

Step 5 — Nginx

Nginx는:

server_name mock-exchange.example.com;

과 일치하는 server block을 찾는다.

그리고:

proxy_pass http://127.0.0.1:3000;

을 확인한다.

Step 6 — Application

Nginx가 내부적으로:

http://127.0.0.1:3000/api/orderbook

으로 요청한다.

Node.js가:

{
  "bids": [],
  "asks": []
}

을 반환한다.

Step 7 — Response

다시:

Node.js
   │
   ▼
Nginx
   │
   │ TLS encryption
   ▼
Internet
   │
   ▼
User

순서로 응답이 돌아간다.

23. 전체 구조를 한 장으로 정리

이번에 우리가 만들 시스템을 전부 합치면 다음과 같다.

                         ┌─────────────────┐
                         │      DNS        │
                         │                 │
                         │ mock-exchange   │
                         │       ↓         │
                         │ EC2 Public IP   │
                         └────────┬────────┘
                                  │
                                  ▼
                              Internet
                                  │
                                  │
                         HTTPS TCP :443
                                  │
                                  ▼
                    ┌─────────────────────────┐
                    │   AWS Security Group    │
                    │                         │
                    │   :80       ALLOW       │
                    │   :443      ALLOW       │
                    │   :3000     BLOCK       │
                    └────────────┬────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │          Nginx          │
                    │                         │
                    │  TLS Certificate        │
                    │  TLS Termination        │
                    │  Reverse Proxy          │
                    │                         │
                    │  mock-exchange...       │
                    │          ↓              │
                    │  127.0.0.1:3000         │
                    └────────────┬────────────┘
                                 │
                                 │ HTTP
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │      Application        │
                    │                         │
                    │ Node.js / Fastify       │
                    │                         │
                    │ 127.0.0.1:3000          │
                    └─────────────────────────┘

24. 그러면 실제 구축 순서는?

이론을 실제 작업으로 바꾸면 순서는 다음과 같다.

① EC2 준비
      ↓
② Node.js 서버 실행
      ↓
③ localhost에서 서버 정상 동작 확인
      ↓
④ Nginx 설치/기존 설정 확인
      ↓
⑤ mock-exchange용 server block 추가
      ↓
⑥ Nginx → Node.js Reverse Proxy
      ↓
⑦ DNS A Record → EC2 IP
      ↓
⑧ HTTP 접속 확인
      ↓
⑨ Let's Encrypt 인증서 발급
      ↓
⑩ Nginx HTTPS 설정
      ↓
⑪ HTTP → HTTPS redirect
      ↓
⑫ HTTPS 접속 확인

이 순서가 중요한 이유는 문제 발생 시 원인을 한 단계씩 분리할 수 있기 때문이다.

25. 장애가 났을 때 어디를 봐야 하는가?

이 구조를 이해하면 장애 원인을 찾기도 쉬워진다.

예를 들어:

https://mock-exchange.example.com

이 안 열린다고 하자.

무작정 Nginx를 수정할 필요가 없다.

먼저:

curl http://127.0.0.1:3000

을 실행한다.

이것부터 실패 : Node.js 문제

curl http://localhost

또는 Host를 지정해서 Nginx를 테스트한다.

여기서 실패한다면: Nginx 문제

dig mock-exchange.example.com

결과가 EC2 IP가 아니면: DNS 문제

443 연결 자체가 안 된다면:

Security Group
Firewall
Nginx listen

등을 확인한다.

인증서 오류라면:

TLS Certificate
Domain
Certbot
Nginx SSL configuration

을 확인한다.

즉 구조를 알고 있으면:

"사이트가 안 돼요"

가 아니라:

DNS?
 ↓
Network?
 ↓
Nginx?
 ↓
TLS?
 ↓
Application?

순서로 문제를 좁힐 수 있다.

26. 자주 혼동하는 것 정리

DNS와 Nginx는 다르다

DNS
Domain → IP

Nginx
Request → Application

HTTP와 HTTPS는 포트가 다르다

HTTP  → 80
HTTPS → 443

SSL과 TLS

현재 실제 사용하는 것은 TLS지만 여전히 관습적으로 “SSL 인증서”라는 표현을 많이 사용한다.

SSL Certificate
≈ TLS Certificate

라고 이해하면 된다.

Let’s Encrypt와 Certbot

Let's Encrypt
→ 인증서를 발급하는 CA

Certbot
→ 인증서 발급/갱신/설정을 자동화하는 Client

Nginx와 Node.js

Nginx
→ 외부 요청 접수
→ HTTPS 처리
→ Reverse Proxy

Node.js
→ 실제 Business Logic/API 처리

Public IP와 Domain

Public IP
→ 실제 서버 주소

Domain
→ 사람이 사용하기 쉬운 이름

DNS
→ Domain과 IP를 연결

27. 이번 작업에서 가장 중요한 개념

모든 내용을 암기할 필요는 없다.

아래 그림이 머릿속에 있으면 된다.

                 DNS
                  │
mock-exchange.example.com
                  │
                  ▼
             EC2 Public IP
                  │
                  │
        ┌─────────┴─────────┐
        │                   │
      HTTP                HTTPS
      :80                  :443
        │                   │
        │             TLS Certificate
        │                   │
        └───────► Nginx ◄───┘
                    │
                    │ Reverse Proxy
                    │
                    ▼
              127.0.0.1:3000
                    │
                    ▼
               Node.js API

그리고 각각 한 문장으로 설명할 수 있으면 충분하다.

DNS :

도메인을 서버의 IP 주소와 연결한다.

HTTP :

클라이언트와 서버가 웹 데이터를 주고받는 프로토콜이다.

HTTPS :

HTTP 통신을 TLS로 보호한 것이다.

TLS :

통신을 암호화하고 무결성을 보호하며 서버의 신원을 인증한다.

TLS Certificate :

해당 서버가 특정 도메인의 서버임을 검증하는 데 사용되는 디지털 인증서다.

Let’s Encrypt :

무료 TLS 인증서를 발급해주는 CA다.

Certbot :

Let’s Encrypt 등의 인증서 발급과 갱신, 웹 서버 설정을 자동화하는 데 사용하는 도구다.

Nginx :

웹 서버이면서 Reverse Proxy 등 다양한 역할을 할 수 있는 소프트웨어다.

Reverse Proxy :

외부 요청을 대신 받아 내부 Application Server로 전달하는 구조다.

TLS Termination :

HTTPS/TLS 처리를 Nginx에서 끝내고 내부 Application에는 HTTP로 전달하는 구조다.

Security Group :

EC2 앞에서 어떤 네트워크 트래픽을 허용할지 제어하는 AWS의 방화벽이다.

마무리

이번에 구축하려는 서버를 한 문장으로 표현하면 다음과 같다.

DNS로 mock-exchange.example.com을 EC2에 연결하고, Nginx가 80/443 포트의 HTTP/HTTPS 요청을 받은 뒤 TLS를 처리하고, Reverse Proxy를 통해 localhost에서 실행 중인 자체 서버로 요청을 전달한다.

그래서 실제 애플리케이션은 인터넷이나 TLS 인증서를 직접 신경 쓰지 않고:

127.0.0.1:3000

에서 자신의 API만 제공하면 된다.

외부 세계와 Application 사이의 경계를 Nginx가 담당하는 것이다.

               External
─────────────────────────────────
DNS
 ↓
AWS Security Group
 ↓
Nginx
 ├─ HTTP
 ├─ HTTPS
 ├─ TLS Certificate
 └─ Reverse Proxy
─────────────────────────────────
               Internal
 ↓
127.0.0.1:3000
 ↓
Application

이 그림을 이해했다면, 이제 실제 Nginx 설정에서 listen, server_name, location, proxy_pass, ssl_certificate가 왜 존재하는지도 자연스럽게 연결된다.

Scafonix (Serverless MPC) 연동기

Sun, 26 Jul 2026 08:33:11 GMT

Scafonix(Serverless MPC)로 지갑 구현하기

제가 지금껏 사용해온 Web2 서비스에서의 이탈 지점은 보통 "필요한 서비스가 아니어서", "재미가 없어서" 같은 이유였습니다. "로그인이 어려워서" 서비스를 그만둔 적은 거의 없었던 것 같습니다.

하지만 Web3에서는 이게 충분히 가능한 이탈 사유가 됩니다. 메타마스크 설치, 네트워크 추가, 시드 문구 백업, 가스비 준비까지 요구하면 사용자는 서비스에 들어오기도 전에 지칩니다. 그렇다고 서버가 개인키를 대신 보관하는 Custodial 방식은 보안적 책임이 너무 큽니다.

이번에는 Scafonix MPC 서비스를 사용해 Google 소셜 로그인만으로 테스트넷 지갑을 만들고, 직접 배포한 SimpleCounter 컨트랙트를 호출해봤습니다. Scafonix는 개인키를 P1, P2, P3로 나누는 2-of-3 MPC 방식입니다. 완성된 개인키를 DB에 저장하거나 서버에서 복구한 뒤 서명하는 구조가 아니라, 브라우저의 보안 샌드박스 안에서 필요한 share를 조합해 서명을 수행합니다. 서비스 제공자 입장에서는 별도의 키 보관 DB나 서명 서버를 운영하지 않아도 된다는 점이 가장 크게 와닿았습니다.

Scafonix Docs를 참고하여 이번 데모를 제작해 봤습니다. Scafonix Docs

Scafonix 에서는 AI Agent 가 활용할 수 있는 프롬프트도 지원하기 때문에 어렵지 않게 구현할 수 있습니다. AI Assistant Docs

1. SimpleCounter

테스트할 컨트랙트는 일부러 단순하게 만들었습니다. 사용자별 count만 저장하고, getCount()는 msg.sender의 count를 반환합니다. count()는 같은 msg.sender의 count를 1 증가시킵니다.

2. Google 로그인으로 지갑 연결

아래는 Scafonix 연동데모를 위해 만든 간단한 페이지 입니다.

클라이언트는 프레임워크 없이 HTML과 JS만 사용했습니다. 단 두줄(ethers 연동을 위한 코드라인을 빼면 단 한줄)만으로도 손쉽게 라이브러리를 불러와서 사용할 수 있습니다.

Google Login 버튼을 누르면 Google OAuth 팝업이 나와서 구글계정으로 손쉽게 로그인할 수 있습니다.

로그인이 완료되면 별다른 과정 없이 나의 지갑이 생성되었고, 생성된 지갑주소를 확인할 수 있습니다.

Google Login만으로 Scafonix Wallet 연결까지 이어지는 간편한 UX가 구현됐습니다.

3. getCount와 count 호출

getCount()는 view 함수라서 단순히 RPC call로 조회했습니다. 다만 컨트랙트가 msg.sender 기준으로 count를 저장하기 때문에, call을 보낼 때도 Scafonix 지갑 주소를 from으로 넣어 현재 로그인한 사용자의 값을 읽었습니다.

const value = await contract.getCount({ from: connectedEvmAddress });

반면 count()는 실제 상태를 바꾸는 함수라 트랜잭션 서명이 필요합니다. Scafonix를 통해 tx에 서명하고 broadcast되는 과정은 아래 4단계로 이해하면 쉽습니다.

클라이언트에서 unsigned tx를 만든다
먼저 to, data, chainId, nonce, gasLimit, fee 값을 채워 아직 서명되지 않은 transaction object를 만듭니다. SimpleCounter.count()의 경우 contract.count.populateTransaction()으로 호출 data를 만들고, RPC에서 nonce와 gas 정보를 조회합니다.
Scafonix SDK에 서명을 요청한다
만든 tx object를 Scafonix.signTransaction(connectedEvmAddress, tx)로 넘깁니다. 여기서 넘기는 것은 개인키가 아니라 서명할 트랜잭션 데이터입니다. device에 저장된 키를 Scafonix 서버로 전송해서 복구하는 구조가 아닙니다.
SDK 보안 샌드박스에서 MPC 서명이 생성된다
Scafonix는 P1, P2, P3 중 필요한 share 조합으로 2-of-3 threshold signing을 수행합니다. 문서 기준으로 이 과정에서도 완성된 private key는 메모리 안에서 조립되지 않습니다. EVM의 경우 결과값은 { r, s, v } 형태의 ECDSA signature입니다.
서명을 붙여 raw transaction을 만들고 RPC에 broadcast한다
반환받은 signature를 ethers의 Transaction.from({ ...tx, signature }).serialized로 붙이면 signed raw transaction이 됩니다. 이 raw transaction을 provider.broadcastTransaction(signedTx)로 네트워크에 전송합니다.

const signature = await Scafonix.signTransaction(connectedEvmAddress, tx);
const signedTx = ethers.Transaction.from({ ...tx, signature }).serialized;
await provider.broadcastTransaction(signedTx);

서비스 제공자가 유저의 개인키를 들고 있지 않은데도, 사용자는 소셜 로그인 이후 자연스럽게 온체인 트랜잭션을 만들 수 있습니다.

4. 백업과 복구

P3는 사용자가 직접 보관하는 복구 share입니다. Google Drive나 copy key share 같은 옵션을 선택할 수 있습니다. 백업 모달은 showBackupModal(userId)로 열 수 있습니다.

Privy와 비교하며 느낀 차이

Privy 같은 Embedded Wallet도 Web3 온보딩 문제를 잘 풀어주는 선택지입니다. 다만 Scafonix는 서비스 제공자 서버 및 DB에 키를 저장하지 않으며, 서명 서버를 두지 않는다는 점이 강점입니다. P1은 브라우저, P2는 소셜 인증 기반 share, P3는 유저가 보관하는 백업 share로 나뉘고, 2-of-3 구조에서 서명이 일어납니다.

물론 "프론트엔드가 해킹돼도 무조건 안전하다"는 뜻은 아닙니다. 악성 트랜잭션 승인, 피싱, 스크립트 공급망 공격은 여전히 별도로 방어해야 합니다. 다만 개인키 전체를 앱이나 서버 및 DB에 저장하지 않는다는 점은 확실히 운영 부담을 줄여줄 수 있다고 생각합니다.

마무리

이번 데모에서는 Scafonix를 연동하여 Google 로그인 한 번으로 지갑 생성부터 연결까지 하고, 직접 배포한 SimpleCounter의 getCount()와 count()까지 호출했습니다. 메타마스크 설치 없이도 온체인 액션을 만들 수 있었고, 서비스 제공자 입장에서는 키를 따로 보관하는 설계를 하지 않아도 되기 때문에 정책적 리스크를 줄일 수 있으며 개별 키 보관 위험도 줄어든다는 점이 좋았습니다. 또한 분리된 키를 따로따로 보관하기 때문에 단일 share 유출만으로는 서명이 불가능하다는 점도 기존 private key 단일 보관 방식보다 안전하게 느껴졌습니다.

ERC-4337 Account Abstraction

Thu, 28 May 2026 09:39:51 GMT

https://eips.ethereum.org/EIPS/eip-4337

Custodial Wallet? Non-Custodial Wallet?

web3 서비스를 이용하다보면 커스터디 월렛, 논-커스터디 월렛이라는 용어를 사용합니다.

Custodial Wallet

서비스 제공자가 사용자의 private key를 대신 보관하고 관리하는 지갑

특징

사용자는 private key를 직접 관리하지 않음
로그인 기반 (이메일, OAuth 등)으로 접근 가능
UX가 Web2 서비스처럼 간단함
서비스가 계정을 복구하거나 접근을 제한할 수 있음

장점

사용하기 쉬움 (초보자 친화적)
사용자의 키 분실 리스크 없음
빠른 온보딩

단점

서비스가 자산을 통제할 수 있음
해킹 또는 내부 사고 시 리스크 큼(SPOF)
“Not your key, not your coin”

Non-Custodial Wallet

Non-Custodial Wallet은 사용자가 자신의 private key를 직접 관리하는 지갑

특징

private key를 사용자 본인이 보관
모든 트랜잭션은 사용자가 직접 서명
!!누구도!! 계정을 임의로 통제할 수 없음

장점

완전한 자산 소유권
검열 저항성
탈중앙성 유지

단점

키 분실 시 복구 불가능
UX가 어렵고 진입장벽 높음
gas fee, 네트워크 이해 필요

Account Abstraction : 계정 추상화

AA 는 왜 등장했는가

기존 EOA의 문제점

모든 tx는 EOA private key 서명이 필요
gas fee는 반드시 ETH로만 지불 가능
ETH Funding이 꼭 필요함
nonce 관리 강제
하나의 private key가 곧 계정 자체
서명 정책 커스터마이징 불가능
recovery / session key / multi-sig 등을 구현하려면 별도 구조 필요

EOA vs Account Abstraction 비교

항목	EOA	AA
서명 주체	Private Key만 가능	원하는 검증 로직 적용 가능
Gas 지불	ETH만 가능	Paymaster를 통해 확장 가능(대납 등)
복구	불가능	가능
멀티시그	외부 구현 필요	내장 가능

Definitions : 구성 항목

UserOperation : 유저 행동을 정의하는 정보를 갖고 있는 데이터 구조체. 흔히 사용하는 transaction과 비슷한 개념이지만 같은 것은 아니기 때문에 UserOperation 이라는 용어 사용
Sender : 추상화된 하나의 계정. UserOperation을 보내는 계정이며, 일반적으로 스마트 컨트랙트 계정(Account Contract)을 의미함
Owner : 추상화된 계정의 주인 계정. Sender에 대한 통제권과 소유권을 갖고있음을 증명할 수 있는 계정이며 일반적으로 Private Key를 사용하는 EOA 계정
EntryPoint : UserOperation을 검증하고 실행하는 중심 컨트랙트. Bundler는 여러 UserOperation을 모아 EntryPoint.handleOps()를 호출하고, EntryPoint는 각 Account의 검증 로직과 실행 로직을 호출함
Bundler : UserOperation mempool에서 UserOperation들을 수집하고, 이를 하나의 일반 Ethereum transaction으로 묶어 EntryPoint에 제출하는 주체
Paymaster : 사용자의 gas 비용을 대신 지불하거나, ETH가 아닌 다른 방식으로 gas 비용을 처리할 수 있게 해주는 선택적 컨트랙트. 예를 들어 서비스가 gas를 sponsor하거나, 사용자가 토큰으로 gas 비용을 지불하는 구조를 만들 수 있음
AccountFactory : Account Contract를 생성하는 컨트랙트. 사용자의 Account가 아직 배포되지 않은 경우, UserOperation의 initCode를 통해 Factory가 Account를 생성할 수 있음
UserOperation mempool : ERC-4337 표준 검증 규칙을 따르는 공개 UserOperation mempool. Bundler들이 공통 규칙에 따라 UserOperation을 수집하고 검증할 수 있도록 설계된 기본 mempool 개념
Deposit : EntryPoint에 예치된 ETH 잔액. Account 또는 Paymaster가 gas 비용 정산을 위해 EntryPoint에 미리 예치해두는 자금

AA 동작방식

userOperation을 생성합니다.

{
  "sender" : "",
  "nonce" : "",
  "factory" : "",
  "factoryData" : "",
  "callData" : "",
  "callGasLimit" : "",
  "verificationGasLimit" : "",
  "preVerificationGas" : "",
  "maxFeePerGas" : "",
  "maxPriorityFeePerGas" : "",
  "paymaster" : "",
  "paymasterVerificationGasLimit" : "",
  "paymasterPostOpGasLimit" : "",
  "paymasterData" : "",
  "signature" : "",

}

생성된 userOperation의 실행 주체는 sender입니다. sender가 생성한 userOp 이 맞다는 서명을 owner 계정을 통해 생성합니다.
생성된 userOperation 과 signature를 alt_mempool 에 제출합니다.
bundler는 alt_mempool에 등록된 userOperation 정보(signature 포함)를 가지고 entryPoint의 handleOps() 함수를 호출합니다.
handleOps() 함수는 내부적으로 account contract의 validateUserOp을 통해 userOperation을 검증합니다.
paymaster가 지정되었다면 validatePaymasterUserOp을 통해 paymaster도 검증합니다.
bundler가 handleOps()를 네트워크에 전송할 때 가스토큰을 지불합니다.
userOperation이 실행이 끝나면 사용한 gas 만큼 bundler가 user/paymaster로부터 돌려받습니다.
user/paymaster의 deposit에서 돌려받게 되며, atomic하게 정산됩니다.

validateUserOp의 의미

기존 Ethereum 에서는

이 트랜잭션이 유효한, 즉 트랜잭션을 전송하는 사람이 계정의 주인이 맞는지

를 검증하기 위하여 ECDSA 서명 검증 로직이 protocol 내부에 고정되어있습니다. : transaction data 를 생성 -> 계정 소유자가 private key로 서명 -> 프로토콜 레벨에서 ECDSA 서명검증 -> 검증 성공 시 tx 실행

하지만 AA 에서는 이 검증 과정을 원하는 방식으로 직접 구현할 수 있으며 그로 인해 다음 기능들을 구현할 수 있습니다.

owner signature 검증
multiSig 검증
특정 시간대만 사용 가능
특정 dApp만 허용
등

기존 Ethereum에서는 “유효한 서명”의 기준이 protocol에 고정되어 있었다면, ERC-4337에서는 그 검증 기준 자체를 Account Contract가 직접 정의할 수 있게 됩니다.

paymaster 예시

사용자는 ETH 없음
서비스는 Paymaster 운영
사용자는 단순 서명만 수행
Paymaster가 gas sponsor
사용자는 Web2처럼 서비스 이용

ERC20 gas payment

사용자는 USDC만 보유

→ Paymaster가 ETH gas를 대신 지불 → 이후 User의 USDC를 차감

AA로 가능한 것들

계정 추상화는 계정들로 하여금 다음을 가능하게 합니다.

가스비 대납
일반 ERC-20 토큰으로 가스비 지불
트랜잭션 배치 실행
계정사용정책 적용
계정 signer 로테이션
등등

마무리

ERC-4337은 단순히 “가스비를 대신 내주는 기술”이 아닙니다.

기존 Ethereum의 EOA는 강력하고 단순했지만, 계정 자체의 동작 방식을 프로그래밍할 수는 없었습니다.

하지만 Account Abstraction에서는 계정(Account)이 하나의 Smart Contract가 되며, “어떤 요청을 유효하다고 판단할 것인가” 자체를 개발자가 정의할 수 있게 됩니다.

즉, 계정이 단순한 private key의 소유 개념을 넘어:

정책을 가질 수 있고
복구 기능을 가질 수 있으며
여러 서명 방식을 사용할 수 있고
서비스 목적에 맞는 UX를 직접 구현할 수 있는

하나의 programmable entity가 됩니다.

그리고 ERC-4337은 이러한 구조를 consensus layer 변경 없이 Ethereum 위에서 구현하기 위한 현실적인 접근입니다.

결국 Account Abstraction은 단순한 기능 추가가 아니라,

“Ethereum 계정 모델 자체를 소프트웨어적으로 확장 가능하게 만든 변화”

라고 볼 수 있겠습니다.

Reentrancy Attack

Fri, 30 Jan 2026 09:40:16 GMT

Reentrancy Attack(재진입 공격)이란?

컨트랙트의 상태가 업데이트 되기 전, 함수를 다시 호출(재진입)하여 공격하는 기법

다음과 같은 기능을 갖고있는 컨트랙트는 reentrancy attack 에 취약합니다.

외부 컨트랙트의 함수를 호출
외부 컨트랙트로 native token 을 전송
자산 전송 이후에 상태업데이트

다음은 Reentrancy 에 취약한 컨트랙트와 이를 공격하는 컨트랙트 코드 예시입니다.

contract vulnerableContract{
    mapping(address => uint256) public balances;

    function withdraw() public{
        require(balances[msg.sender] > 0);

        (bool success, ) = msg.sender.call{value: balances[msg.sender]}("");
        require(success);

        balances[msg.sender] = 0;
    }
}

contract maliciousContract{
    IVulnerableContract public vCa = "0xsomeAddress..";

    function exploit() external {
        vCa.withdraw();
    }

    fallback() external payable {
        if(address(vCa).balance >= vCa.balances(address(this))){
            vCa.withdraw();
        }
    }
}

위의 두 컨트랙트는 다음과 같은 흐름으로 exploit이 됩니다.

대응법

1. 자산 전송 전 상태업데이트 먼저 하기

contract safeContract{
    mapping(address => uint256) public balances;

    function withdraw() public{
        require(balances[msg.sender] > 0);

        uint256 transferAmount = balnaces[msg.sender];
        balances[msg.sender] = 0;

        (bool success, ) = msg.sender.call{value: transferAmount}("");
        require(success);
    }
}

상태(msg.sender 의 balance) 업데이트 → 자산 전송 의 순서로 코드가 실행되면 재진입을 하더라도 잔액을 확인하는 부분에서 오류가 발생하기 때문에 재진입 공격에 실패하게 됩니다.

2. Mutex 사용

contract safeContract{
    mapping(address => uint256) public balances;
    bool mutex = false;

    function withdraw() public{
        require(!mutex, "Mutex is locked");
        require(balances[msg.sender] > 0, "Insufficient balance");

        mutex = true;

        (bool success, ) = msg.sender.call{value: balances[msg.sender]}("");
        require(success, "tx is failed");

        balances[msg.sender] = 0;

        mutex = false;
    }
}

재진입을 하더라도 mutex가 잠겨있는 상태이기 때문에 tx가 실패하게 됩니다.

3. Openzeppelin ReentrancyGuard 사용

import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

contract safeContract {
    mapping(address => uint256) public balances;

    function withdraw() public nonReentrant{
        require(balances[msg.sender] > 0, "Insufficient balance");

        (bool success, ) = msg.sender.call{value: balances[msg.sender]}("");
        require(success, "tx is failed");

        balances[msg.sender] = 0;
    }
}

mutex와 동일한 원리입니다. openzeppelin 에서 표준화한 코드를 사용합니다.

홈 서버 구축기 - 초기세팅

Fri, 09 Jan 2026 14:23:32 GMT

램트코인 이라는 말이 나올 정도로 메모리, ssd 가격이 천정부지로 올라가고 있습니다.

여느때와 같이 당근을 보던 중

신품기준 무려 약 29만원짜리 상품을 단돈 13만원에 판매한다는 글을 보았고, 바로 메세지를 보냈습니다.

오케이 굿. 바로 구매 ㄱㄱ

연락을 한 다음 날 바~~로 집으로 데려왔습니다.

케이스는 군시절이 떠오르는 국방색이고 사이즈는 수첩? 정도의 아주 작고 귀여운 미니PC 입니다.

이 친구를 처음 데려왔을 때에는 윈도우11 이 설치되어 있었습니다.

저는 개발자기 때문에(?) 바로 우분투를 깔기로 마음먹었습니다.

또한, 그냥 개발자가 아닌 "BackEnd Developer" 이기 때문에, GUI 따위 필요없다 선언하고 바~로 Ubuntu Server 를 설치했습니다.

화면에 딱 한줄 띄워져 있는 모습, 아주 멋있지 않나요?

그런데, 막상 설치하고 나니 무인도에 알몸으로 던져진 느낌이었습니다.

인터넷 조차 직접 설정해야 되더라구요.. 새삼 GUI의 편리함을 느끼게 되는 계기였습니다.

패기롭게 시작하였지만 아는게 없는 저는 바~로 GPT선생님께 질문하였고 역시나 갓갓갓선생님께서는 설정법을 아주 쉽게 알려주셨습니다.

먼저 ip a 명령어를 입력해서 사용할 수 있는 랜카드를 확인합니다.

확인 결과, 유선랜포트는 enp3s0 라고 라고 돼있었습니다.

인터넷에 연결하기 위해 /etc/netplan/00-wired.yaml 파일을 생성해주고 다음 내용을 작성했습니다.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp3s0:
      dhcp4: true

그 다음 ~$ sudo netplan apply 로 설정파일 적용!

~$ ping 8.8.8.8 명령어를 통해 인터넷 연결이 잘 되었는지 (google dns 서버와 통신이 되는지) 확인을 하고

ssh를 설치했습니다

apt install -y openssh-server systemctl enable ssh systemctl start ssh

짜라란~ 접속 성공!

자, 그럼 이제 무엇을 해볼지 고민을 해야합니다.

Websocket을 활용한 event indexing

Fri, 09 Jan 2026 05:49:54 GMT

github

https://github.com/natreeum/HybridIndexer

개요

기존 인덱싱 방식은 http 방식(Polling)으로 진행. 이로인해 설정된 주기로만 요청하므로 최대 ‘설정된 주기까지의 delay’가 생김. 이로 인해 낙관적 업데이트와 같은 추가 작업을 필요로 합니다.

구상

ws provider를 통한 event subscription으로 event 발생 시 트랜잭션(event) 수집
웹소켓으로 수집된 트랜잭션은 DB에 저장 a. 최초 status 는 unconfirmed상태로 저장
batch indexing을 통해 unconfirmed 상태의 트랜잭션에 대해 confirm a. removed : true 인 경우(reorg) 삭제 b. 누락된 데이터 업데이트
ws connection 이 유실되었을 경우 재연결 시도

0. Contract

Event 를 emit 하는 단순한 컨트랙트 배포

code : Test.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract Test {
    event LogMessage(string message);
    event TestTransfer(address indexed from, address indexed to, uint256 value);

    function emitLogMessage(string memory message) public {
        emit LogMessage(message);
    }

    function transfer(address to, uint256 value) public {
        emit TestTransfer(msg.sender, to, value);
    }
}

1. Websocket으로 Emit되는 event 확인

code : indexer.js

const { ethers } = require("ethers");
module.exports = class HybridIndexer {
  constructor({
    wsUrl,
    httpUrl,
    contractCfg, // {address, abi}
    events, // ["Transfer", ...]
    confirmations = 10,
    chunkSize = 2000,
    poolIntervalMs = 5000,
  }) {
    this.wsUrl = wsUrl;
    this.httpUrl = httpUrl;
    this.contractCfg = contractCfg;
    this.events = events;
    this.confirmations = confirmations;
    this.chunkSize = chunkSize;
    this.poolIntervalMs = poolIntervalMs;

    this.wsProvider = null;
    this.httpProvider = null;
    this.wsContract = null;
    this.httpContract = null;
    this.running = false;
  }

  async start() {
    this.running = true;

    this.wsProvider = new ethers.WebSocketProvider(this.wsUrl);
    this.httpProvider = new ethers.JsonRpcProvider(this.httpUrl);

    this.wsContract = new ethers.Contract(
      this.contractCfg.address,
      this.contractCfg.abi,
      this.wsProvider
    );
    console.log(`WebSocket Provider connected to ${this.wsUrl}`);

    this.httpContract = new ethers.Contract(
      this.contractCfg.address,
      this.contractCfg.abi,
      this.httpProvider
    );
    console.log(`HTTP Provider connected to ${this.httpUrl}`);

    this._subscribeEvents();
    console.log("HybridIndexer started");
  }

  _subscribeEvents() {
    this.events.forEach((eventName) => {
      this.wsContract.on(eventName, async (...args) => {
        console.log(args);
      });
    });
  }
};

code : server.js

const express = require("express");
const Indexer = require("./indexer/hybridIndexer");

const app = express();

// Fuji Network configuration
const wsUrl = "wss://api.avax-test.network/ext/bc/C/ws";
const httpUrl = "https://api.avax-test.network/ext/bc/C/rpc";
const abi = require("./abi/ABI.json"); // 예시 ABI 파일
const contractAddress = "0xa85761417ed8ae28378612a63282b4A576949377";
const contractCfg = {address : contractAddress, abi}
const events = ["LogMessage","TestTransfer"]

app.get("/", (req, res) => {
  return res.send("Hello, World!");
});

const indexer = new Indexer({
  wsUrl,
  httpUrl,
  contractCfg, // ethers.Contract Instance
  events, // ["Transfer", ...]
});


indexer.start()

app.listen(3000, () => {
  console.log("Server is running on port 3000");
});

서버를 실행하면 indexer가 실행되고, events에 대해 subscription 실행

Test.sol 의 LogMessage Event 발생 시 서버측에서 이벤트 확인

2. DB Table

확장성을 고려해서 공통 column / eventArgs column을 구분

공통 column

transaction_hash
block_number
log_index
transaction_index
confirmed

Event Args Column

3. Indexer Constructor

wsUrl : WebSocket RPC URL
httpUrl : http RPC URL
contractCfg
- address : 컨트랙트 주소
- abi : 컨트랙트 abi
eventName : 받아올 event의 이름
tableName : 받아온 event data 를 저장하는 table 이름
argKeys : args 이름 배열 [”eventArgName1”, “eventArgName2”]
confirmations : block confirmation 수
chunkSize : polling 최대 블록 수
pollIntervalMs : polling 인터벌 ms
pingIntervalMs : ws connection status 체크를 위한 ping 인터벌 ms

구현

Hybrid Indexer

const { ethers } = require("ethers");
const log = require("../libraries/timestampLog");
const insertEvent = require("../database/insert");
const updateEvent = require("../database/update");
const deleteEvent = require("../database/delete");
const updateLastQueryBlockNumber = require("../database/updateLastQueryBlock");
const getLastBlockNumber = require("../database/getLastBlockNumber");
const getEvent = require("../database/getEvent");

module.exports = class HybridIndexer {
  constructor({
    wsUrl,
    httpUrl,
    contractCfg, // {address, abi}
    eventName,
    tableName,
    argKeys, // ["eventArgName1", "eventArgName2"]
    confirmations = 10,
    chunkSize = 1000,
    pollIntervalMs = 30000, // Default 30 seconds
    pingIntervalMs = 300000, // Default 5 minutes
  }) {
    this.wsUrl = wsUrl;
    this.httpUrl = httpUrl;
    this.contractCfg = contractCfg;
    this.eventName = eventName;
    this.confirmations = confirmations;
    this.chunkSize = chunkSize;
    this.pollIntervalMs = pollIntervalMs;
    this.intervalPoll = null;
    this.mutexLock = false;
    this.lastConfirmedBlock = 0;

    this.wsProvider = null;
    this.httpProvider = null;
    this.wsContract = null;
    this.httpContract = null;

    this.tableName = tableName;
    this.argKeys = argKeys;

    this.intervalPing = null;
    this.pingIntervalMs = pingIntervalMs;

    this.running = false;
  }

  async start() {
    this.running = true;

    this.wsProvider = new ethers.WebSocketProvider(this.wsUrl);
    this.httpProvider = new ethers.JsonRpcProvider(this.httpUrl);

    this.wsContract = new ethers.Contract(
      this.contractCfg.address,
      this.contractCfg.abi,
      this.wsProvider
    );
    log(`WebSocket Provider is set to ${this.wsUrl}`);
    this.wsProvider.websocket.on("open", () => {
      log(`WebSocket connected to ${this.wsUrl}`);
    });

    this.httpContract = new ethers.Contract(
      this.contractCfg.address,
      this.contractCfg.abi,
      this.httpProvider
    );
    log(`HTTP Provider is set to ${this.httpUrl}`);

    this._subscribeEvents();
    log("HybridIndexer started");

    // reconnect on error
    this.wsProvider.websocket.on("error", () => {
      log(`WebSocket Error Occurred`);
      this.wsProvider?.removeAllListeners?.();
      log(`Removing all listeners from WebSocket Provider`);
      this.wsProvider?.destroy?.();
      log(`WebSocket Provider destroyed`);

      if (this.running) {
        log("Attempting to reconnect...");
        this.start();
      }
    });

    // reconnect on close
    this.wsProvider.websocket.on("close", () => {
      log(`WebSocket Connection Closed`);
      this.wsProvider?.removeAllListeners?.();
      log(`Removing all listeners from WebSocket Provider`);
      this.wsProvider?.destroy?.();
      log(`WebSocket Provider destroyed`);

      // Reconnect if still running
      if (this.running) {
        log("Attempting to reconnect...");
        this.start();
      }
    });

    // To keep the WebSocket connection alive, send periodic pings
    this.intervalPing = setInterval(() => {
      if (this.wsProvider.websocket.readyState === 1) {
        this.wsProvider.websocket.ping();
        log("WebSocket ping sent");
      } else {
        log("WebSocket is not open, skipping ping");
      }
    }, this.pingIntervalMs);

    this._confirmEvents();
  }

  stop() {
    this.running = false;
    try {
      this.wsProvider?.removeAllListeners?.();
      this.wsProvider?.destroy?.();
      this.wsProvider = null;
    } catch (error) {
      error("Error stopping WebSocket Provider:", error);
    }

    // Clear the ping interval if it exists
    if (this.intervalPing) {
      clearInterval(this.intervalPing);
      this.intervalPing = null;
      log("Ping interval cleared");
    }

    log("HybridIndexer stopped");
  }

  _subscribeEvents() {
    this.wsContract.on(this.eventName, async (...args) => {
      const event = args[args.length - 1]; // ethers v6: 마지막 인자가 Event

      await insertEvent({
        tableName: this.tableName,
        transactionHash: event.log.transactionHash,
        blockNumber: event.log.blockNumber,
        logIndex: event.log.index,
        transactionIndex: event.log.transactionIndex,
        argKeys: this.argKeys,
        argValues: event.log.args,
      });
      log(
        `Event has been inserted into the database : ${event.log.blockNumber}-${event.log.index}-${event.log.transactionIndex}`
      );
    });
    log(`Subscribed to event: ${this.eventName}`);
  }

  _confirmEvents() {
    this.intervalPoll = setInterval(async () => {
      if (this.mutexLock) {
        console.log(`Mutex is locked`);
        return;
      }
      this.mutexLock = true;
      try {
        const network = await this.httpProvider.getNetwork();
        const lastBlockNumber = await getLastBlockNumber({
          eventName: this.eventName,
          contractAddress: this.contractCfg.address,
          networkId: network.chainId.toString(),
        });
        console.log("last block number : ", lastBlockNumber);
        const currentBlockNumber = await this.httpProvider.getBlockNumber();
        console.log("Current block number : ", currentBlockNumber);
        const filter = this.httpContract.filters[this.eventName]();

        const fromBlockNumber = lastBlockNumber + 1;
        const toBlockNumber = Math.min(
          currentBlockNumber - this.confirmations,
          fromBlockNumber + this.chunkSize
        );
        console.log(fromBlockNumber);
        console.log(toBlockNumber);

        // invalid block range
        if (fromBlockNumber >= toBlockNumber) {
          console.log(
            `Block range is invalid: from:${fromBlockNumber} >= to:${toBlockNumber}`
          );
          throw new Error(`Invalid block range`);
        }

        const events = await this.httpContract.queryFilter(
          filter,
          fromBlockNumber,
          toBlockNumber
        );

        for (const e of events) {
          const {
            transactionHash,
            blockNumber,
            removed,
            index,
            transactionIndex,
            args,
          } = e;
          // Check if this event exist on db
          const exists = await getEvent({
            tableName: this.tableName,
            transactionHash,
            blockNumber,
            index,
            transactionIndex,
          });
          if (exists.length > 0) {
            if (!removed) {
              // if the event is not removed, update "confirmed" as 1
              await updateEvent({
                tableName: this.tableName,
                transactionHash,
                blockNumber,
                index,
                transactionIndex,
              });
            } else {
              // if the event is removed, delete the row
              await deleteEvent({
                tableName: this.tableName,
                transactionHash,
                blockNumber,
                index,
                transactionIndex,
              });
            }
          } else {
            // if the event is not exist on db, insert it
            await insertEvent({
              tableName: this.tableName,
              transactionHash,
              blockNumber,
              logIndex: index,
              transactionIndex,
              argKeys: this.argKeys,
              argValues: args,
            });
          }
        }
        console.log(`${events.length} events processed`);
        await updateLastQueryBlockNumber({
          tableName: "event_query_info",
          eventName: this.eventName,
          contractAddress: this.contractCfg.address,
          networkId: network.chainId.toString(),
          lastQueryBlockNumber: toBlockNumber,
        });
      } catch (e) {
        console.log(e);
      } finally {
        this.mutexLock = false;
      }
    }, this.pollIntervalMs);
  }

  websocketStatus() {
    return this.wsProvider?.websocket?.readyState === 1
      ? "Connected"
      : "Disconnected";
  }
};

서버 실행

Event 발생 시 즉시 DB에 row 생성

새로운 row 확인

새로운 row가 insert된 내용의 log

Polling 으로 Tx Confirm

confirmed status 가 0->1 로 변경됨

server - confirmed event log

Websocket Ping 으로 health check

Polling 할 block range 를 기록하기 위한 테이블

Multicall Contract 취약점 사례

Thu, 08 Jan 2026 07:01:44 GMT

Uniswap Multicall

Uniswap Multicall 컨트랙트의 코드를 살펴보면 다음과 같습니다.

Call 이라는 data struct를 배열로 받고, target.call() 을 통해 배열로 전달된 callData 를 target contract에 실행시킵니다.

여기서 해당 tx의 실행 주체는 uniswap multicall contract가 됩니다.

이를 악용한 공격 수법을 알아보겠습니다.

공격자는 피해자에게 다음과 같은 Approve 트랜잭션에 서명하도록 합니다.

Spender : Uniswap Multicall Contract
Amount : uint256 최대치

피해자의 입장에서는 수많은 트랜잭션이 일어나고, 유명한 Uniswap 컨트랙트가 spender 이므로 별다른 의심없이 해당 트랜잭션에 서명하게 됩니다.

이 과정에서 Uniswap Contract는 피해자의 지갑이 보유하고 있는 토큰에 대한 제어권을 갖게 됩니다.

Uniswap Contract가 피해자의 토큰에 대한 제어권을 갖게 되면, 공격자는 Uniswap Contract에 대해 transferFrom 메소드를 다음과같이 호출합니다.

sender : 피해자 지갑주소
recipient : 공격자 지갑 주소
amount : 수량

여기서 transferFrom 은 다음과 같이 작동합니다. transferFrom(sender, recipient, amount); tx를 전송하는 주체(msg.sender)는 sender로 부터 allowance 를 취득해야하고, allowance가 충분할 경우 sender의 지갑에서 recipient에게 amount만큼 전송합니다.

이 과정을 도식화 하면 다음과 같습니다.

Gnosis Safe

비슷한 사례로 Gnosis safe wallet (multi sig wallet)을 통한 공격도 있었습니다.

공격의 순서는 다음과 같습니다

공격자는 safe wallet(proxy)을 생성합니다
공격자는 피해자에게 safe wallet에 대한 approve를 서명하도록 유도합니다.
피해자가 approve tx에 서명을 하면, 공격자는 proxy 컨트랙트의 execTransaction 메소드를 호출
proxy 컨트랙트는 마스터 컨트랙트의 execTransaction을 delegateCall을 통해 호출

이 과정을 도식화 하면 다음과 같습니다.

개발 시 주의할 점

공개된 multicall contract 에 approve 를 수행해서는 절대 안됨
multicall 기능이 필요하다면, tx를 대신해서 수행하는 메소드에 권한을 추가하여(whitelisted) 제한적으로 사용

참고 : https://research.checkpoint.com/2024/unveiling-the-scam-how-fraudsters-abuse-legitimate-blockchain-protocols-to-steal-your-cryptocurrency-wallet/

Off-chain message Signing 검증하기 (EIP-712)

Wed, 07 Jan 2026 07:43:22 GMT

https://eips.ethereum.org/EIPS/eip-712

EIP-712

EIP-712 는 트랜젝션 데이터가 아닌 모든 데이터를 어떤 구조로 서명할 지에 대해 정의한 제안이며 사용자에게 서명할 메세지를 사람이 읽을 수 있는 구조로 보여주고, 그 구조에 따라 서명하여 신뢰성과 보안성을 높이는데 초점을 둡니다.

핵심 요소

TYPE_HASH

TYPE_HASH 는 기능이름(parameters) 로 된 문자열을 keccak256 으로 해싱 한 값입니다.

EIP712Domain 에 대한 TYPE_HASH 는 다음과 같습니다.

keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");

domainSeperator

어떤 네트워크의 어떤 컨트랙트에서 사용되는(검증되는) 서명인지 구분하기 위한 구분자.

DomainSeperator 의 구성은 다음과 같습니다.

string name : 컨트랙트(DApp 혹은 Protocol)의 이름
string version : 컨트랙트 버전
uint256 chainId : 컨트랙트가 배포된 네트워크 아이디
address verifyingContract : 서명을 검증하는 컨트랙트의 주소(배포된 컨트랙트 주소)

Openzeppelin 에서 DomainSeperator를 생성하는 코드는 다음과 같습니다. (EIP712.sol#L90)

function _buildDomainSeparator() private view returns (bytes32) {
    return keccak256(abi.encode(TYPE_HASH, _hashedName, _hashedVersion, block.chainid, address(this)));
}

encodeType

Parameter 로 전달되는 인자의 type을 정의한 정의서. encodeType을 통해 해당 함수에 대한 TYPE_HASH 가 생성됩니다.

예시

const type = {
    transfer: [
      {name:"to", type:"address"},
      {name:"amount", type:"uint256"},
    ]
};

encodeData

Parameter 로 전달되는 인자의 값

예시

const data = {
    to : wallet.address,
      amount : 1000000000000000000n
};

검증 과정

signer는 private key 를 사용하여 메세지를 서명합니다. 서명된 메세지는 다음 데이터들로부터 생성됩니다.
- domainSeperator
- encodeType
- encodeData
서명된 메세지(signature)는 v, r, s 로 분리됩니다.
- v, r, s 는 ECDSA(타원곡선을 이용한 전자서명알고리즘)을 위한 값
함수 호출자는 서명된 데이터(v,r,s) 와 arguments 를 함께 전달합니다.
함수에서는 전달받는 arguments 와 v,r,s 값으로 ecrecover 함수를 통해 해당 서명을 검증합니다.

a. 서명에 사용된 값과 arguments 값이 일치하면 ecrecover 는 서명자의 주소를 반환합니다.

b. 서명에 사용된 값과 arguments 값이 일치하지 않을경우 ecrecover 는 엉뚱한 주소를 반환합니다.

예시
1. owner 가 to:0x1234, amount:100 값에 대해 서명하여 Signature 생성
2. 함수호출자가 to:0x1234, amount:9000000 라는 값을 Owner 의 Signature 와 함께 호출
-> 검증 과정에서 ecrecover 가 엉뚱한 주소를 반환하여 검증 실패

1. owner 가 to:0x1234, amount:100 값에 대해 서명하여 Signature 생성
2. 함수호출자가 to:0x1234, amount:100 라는 값을 Owner 의 Signature 와 함께 호출
-> 검증 과정에서 ecrecover 가 owner의 주소를 반환하여 검증 성공

컨트랙트 코드를 함께 보며 이해도를 높이면 좋을것 같습니다. 다음은 설명을 위한 컨트랙트의 함수 코드입니다.

// mintWithApproval() 은 owner의 private key 로 sign 된 메세지(signature)가 정상일 때 민팅을 할 수 있는 함수입니다.
function mintWithApproval(
    address to,
    uint256 amount,
    uint8 v,
    bytes32 r,
    bytes32 s
) external {
    // 함수의 TYPE_HASH 와 전달받은 arguments 로 structHash 를 생성합니다.
    bytes32 structHash = keccak256(
        abi.encode(
            keccak256("mintWithApproval(address to,uint256 amount)"), // TYPE_HASH
            to, // arg1
            amount // arg2
        )
    );

    bytes32 hash = _hashTypedDataV4(structHash);

    // 서명된 데이터(v,r,s) 에 사용된 데이터와 arguments(to, amount) 값이 같다면 ecrecover 는 서명한 지갑의 주소를 반환합니다.
    address signer = ecrecover(hash, v, r, s);


    if (signer != owner) {
        revert("Invalid signature");
    }

    _mint(to, amount);
}

EIP-712 를 따르는 서명 생성하기

EIP-712 를 따르는 서명을 만드는 방법은 다양하겠지만 이 글에서는 ehters.js 라이브러리로 서명을 생성하는 방법만 다뤄보겠습니다.

ethers.js

도메인 지정

domainSeperator 생성을 위한 도메인을 지정해줍니다.

const domain = {
    name: "Test",
      version: "1",
      chainId: 1,
      verifyingContract: "0x1234contractAddress"
};

Type 지정

parameter 로 전달할 인자들의 타입을 지정해줍니다.

const types = {
    mintWithApproval:[
      {name: "to", type: "address"},
      {name: "amount", type: "uint256"},
    ]
};

Data 지정

parameter 로 전달할 인자들의 값을 지정해줍니다.

const data = {
    to: "0x9876walletAddress",
      amount: 1000000000000000000n
};

Signature 생성 + vrs 로 분리

ethers 의 Wallet instance 로 서명을 생성합니다.

const owner = ethers.Wallet.createRandom();

const signature = owner.signTypedData(domain, types, data);

const {v, r, s} = ethers.Signature.from(signature);

Easy Rust Korean 051 ~ 060

Sun, 30 Nov 2025 12:36:43 GMT

051

HashMap : key - value

key와 value 는 어떤 타입도 될 수 있음

(key)String -> (value)Vec 의 hashMap 을 만들고 싶다면 다음과 같이 사용

// HashMap>

hashMap example

use std::collections::HashMap;

struct City{
    name: String,
    population: HashMap // year -> population
}

fn main(){
    let mut tallin = City {
        name : "Tallin".to_string(),
        population: HashMap::new()
    };

    tallin.population.insert(1372, 3_250);
    tallin.population.insert(1851, 24_000);
    tallin.population.insert(2020, 437_619);

    for(year, population) in tallin.population{
        println!("In the year {} the population was {}", year, population)
    }
}

1372년, 1851년, 2020년의 순서로 나오지 않음. (순서는 완전 랜덤)

hashMap 은 순서를 정의할 수 없는 특징이 있음.

BTreeMap : ordering 이 가능한 HashMap

order가 필요없다면 HashMap, 필요하다면 BTreeMap(상대적으로 느림)

BTreeMap 예시

use std::collections::BTreeMap;

struct City{
    name: String,
    population: BTreeMap // year -> population
}

fn main(){
    let mut tallin = City {
        name : "Tallin".to_string(),
        population: BTreeMap::new()
    };

    tallin.population.insert(1372, 3_250);
    tallin.population.insert(1851, 24_000);
    tallin.population.insert(2020, 437_619);

    for(year, population) in tallin.population{
        println!("In the year {} the population was {}", year, population)
    }
}
// 1372년 -> 1851년 -> 2020년 순서가 보장됨

052

HashMap 의 값을 불러오는 방법

(안전x 방법)

use std::collections::HashMap;

fn main(){
    let canadian_cities = vec!["Calgary", "Vancouver", "Gimli"];
    let german_cities = vec!["Karlsruhe", "Bad Doberan", "Bielefeld"];

    let mut city_hashmap = HashMap::new();

    for city in canadian_cities{
        city_hashmap.insert(city, "Canada");
    }

    for city in german_cities{
        city_hashmap.insert(city, "Germany");
    }

    println!("{:?}", city_hashmap["Bielefeld"]); // 정상 출력 (Bielefeld 라는 key가 존재함)

    println!("{:?}", city_hashmap["Bielefeld123"]); // key 가 존재하지 않아서 오류 발생 
}

(안전한 방법, .get 사용) .get을 사용하면 "None"을 반환

use std::collections::HashMap;

fn main(){
    let canadian_cities = vec!["Calgary", "Vancouver", "Gimli"];
    let german_cities = vec!["Karlsruhe", "Bad Doberan", "Bielefeld"];

    let mut city_hashmap = HashMap::new();

    for city in canadian_cities{
        city_hashmap.insert(city, "Canada");
    }

    for city in german_cities{
        city_hashmap.insert(city, "Germany");
    }

    println!("{:?}", city_hashmap.get("Bielefeld")); // Some("Germany") 출력

    println!("{:?}", city_hashmap.get("Bielefeld123")); // None 출력
}

이미 값이 존재하는 key 에 대해 insert하게 되면 덮어쓰기가 됨.

use std::collections::HashMap;

fn main(){
    let mut book_hashmap = HashMap::new();

    book_hashmap.insert(1, "Book1");
    book_hashmap.insert(1, "Book2");
    book_hashmap.insert(1, "Book3");
    book_hashmap.insert(1, "Book4");

    println!("{:?}", book_hashmap.get(&1)); // hashmap 에게 소유권을 넘기지 않고 reference 만 제공하기 위해 &1 사용
}

is_none 활용

use std::collections::HashMap;

fn main(){
    let mut book_hashmap = HashMap::new();

    book_hashmap.insert(1, "Book1");

    if book_hashmap.get(&1).is_none() {
        book_hashmap.insert(1, "Book1");
    } else {
        println!("Already got a book");
    }
}

if let 활용

use std::collections::HashMap;

fn main(){
    let mut book_hashmap = HashMap::new();

    book_hashmap.insert(1, "Book1");

    if let Some(book_name) = book_hashmap.get(&1) {
        println!("Already got a book : {}", book_name);
    } else {
        book_hashmap.insert(1, "Book1");
    }
}

053

Entry Method

use std::collections::HashMap;

fn main(){
    let book_collection = vec![
        "book1",
        "book2",
        "book3",
        "book4",
        "book4",
    ];

    let mut book_hashmap = HashMap::new();

    for book in book_collection{
        book_hashmap.entry(book).or_insert(true);
    }

    for (book, true_or_false) in book_hashmap{
        println!("Do we have {}? : {}", book, true_or_false);
    }
}

.entry() method

pub fn entry(&mut self, key: K) -> Entry

pub enum Entry<'a, K: 'a, V: 'a> {
    Occupied(OccupiedEntry<'a, K, V>),
    Vacant(VacantEntry<'a, K, V>),
}

Entry.or_insert() 는 &'a mut 을 반환하기 때문에 값을 바꿀 수 있음

use std::collections::HashMap;

fn main(){
    let book_collection = vec![
        "book1",
        "book2",
        "book3",
        "book4",
        "book4",
    ];

    let mut book_hashmap = HashMap::new();

    for book in book_collection{
        let number_of_books = book_hashmap.entry(book).or_insert(0); // number_of_books -> &ref
        *number_of_books += 1;
    }

    for (book, number) in book_hashmap{
        println!("{}: {}copies", book, number);
    }
}

054

use std::collections::HashMap;

fn main(){
    let data = vec![
        ("male", 9),
        ("female", 5),
        ("male", 0),
        ("female", 6),
        ("female", 5),
        ("male", 10),
    ];

    let mut survey_hash = HashMap::new();

    for item in data { // (&str, i32)
        survey_hash.entry(item.0).or_insert(Vec::new()).push(item.1);
    }

    for (male_or_female, numbers) in survey_hash{
        println!("{:?}, {:?}", male_or_female, numbers)
    }
}

HashSet

use std::collections::HashSet;

fn main(){
    let many_numbers = vec![1,3,5,7,7,9];

    let mut number_hashset = HashSet::new();

    for number in many_numbers {
        number_hashset.insert(number);
    }

    let hashset_length = number_hashset.len(); // hashset length
    println!("There are {} unique numbers, so we are missing {}", hashset_length, 10-hashset_length);

    let mut missing_vec = vec![];
    for number in 0..10{
        if number_hashset.get(&number).is_none() {
            missing_vec.push(number);
        }
    }

    print!("Missing numbers : ");
    for number in missing_vec{
        print!("{} ", number);
    }
}

Set 에서도 Map과 동일하게 순서가 중요하다면 BTreeSet 사용!

055

binaryHeap : 아직 실제로 써본적은 없다고 함

use std::collections::BinaryHeap;

fn show_remainder(input: &BinaryHeap) -> Vec {
    let mut remainder_vec = vec![];
    for number in input {
        remainder_vec.push(*number)
    }
    remainder_vec
}

fn main(){
    let many_numbers = vec![0, 5, 10, 15, 20, 25, 30];

    let mut my_heap = BinaryHeap::new();

    for number in many_numbers{
        my_heap.push(number);
    }

    while let Some(number) = my_heap.pop(){
        println!("Popped off {}. Remaining numbers are : {:?}", number, show_remainder(&my_heap));
    }
}
/* Output
Popped off 30. Remaining numbers are : [25, 15, 20, 0, 10, 5]
Popped off 25. Remaining numbers are : [20, 15, 5, 0, 10]
Popped off 20. Remaining numbers are : [15, 10, 5, 0]
Popped off 15. Remaining numbers are : [10, 0, 5]
Popped off 10. Remaining numbers are : [5, 0]
Popped off 5. Remaining numbers are : [0]
Popped off 0. Remaining numbers are : []
*/

-> 첫 번째 요소는 가장 큰 값, 나머지 요소들의 순서는 일관되지 않음

056

VecDeque

Vec의 경우

fn main(){
    let my_vec = vec![8,9,10];
}

.pop : 맨 마지막값을 뺌 .push : 맨 마지막에 값을 넣음 Vec::with_capacity(10) : reallocation 없이 빠르게 사용

.remove(idx) : idx 의 값을 빼고 나머지 값들의 idx 를 한자리씩 앞으로 이동시킴

다음 상황에서 연산량이 많아서 오래걸리는 처리를 VecDeque 를 사용해서 빠르게 처리할 수 있음

// 오래 걸리는 코드
fn main(){
    let mut my_vec = vec![0; 600_000]; // 0이 60만개있는 vec
    for i in 0..600_000 {
        my_vec.remove(0);
    }
}

// VecDeque 사용
use std::collections::VecDeque;

fn main(){
    let mut my_vec = VecDeque::from(vec![0; 600_000]);
    for i in 0..600_000{
        my_vec.pop_front();
    }
}

Ring buffer 를 이용해서...........빠름

057

use std::num::ParseIntError "8" 같은 값을 int로 변환, "8eo"같은 값은 에러 반환

use std::num::ParseIntError;

fn parse_str(input:&str) -> Result{
    let parsed_number = input.parse::()?; // 성공하면 넘어감 실패하면 return error
    Ok(parsed_number)
}

fn main(){
    for item in vec!["seven", "8", "9.0", "nice","6060"]{
        let parsed = parse_str(item);
        println!("{:?}", parsed);
    }
}

/*
Err(ParseIntError { kind: InvalidDigit })
Ok(8)
Err(ParseIntError { kind: InvalidDigit })
Err(ParseIntError { kind: InvalidDigit })
Ok(6060)
*/

058

https://play.rust-lang.org/ 에서 monaco editor 지원 시작 -> 인텔리센스(자동완성) 가능

format Strings

기존에는 다음과같이 써야만 했다면 println!("Books\n- {:?}\n- {:?}, book1, book2)

업데이트 이후에는 다음과같이 쓸 수 있게 됨 println!("Books\n- {book1:?}\n- {book2:?})

#[derive(Debug)]
struct Book{
    title: String,
    year: u16
}

fn main(){
    let book1 = Book{
        title : "Some title".to_string(),
        year: 1919
    };
    let book2 = Book{
        title : "Book2".to_string(),
        year: 2020
    };

    println!("Books\n{book1:?}\n{book2:?}");

    /* 아직 struct 안의 property 는 지원안함 */
    // println!("My book name : {book1.title});
}

059, 60

traits (다른 언어의 interface와 비슷)

struct Animal {
    name : String
}

trait Canine {
    fn bark(&self){
        println!("Woof Woof!");
    }
    fn run(&self){
        println!("I am running!");
    }
}

impl Canine for Animal{
    // 덮어쓰기 가능
    fn bark(&self){
        println!("멍멍!");
    }
}

fn main(){
    let my_animal = Animal{
        name : "Mr. Mantle".to_string()
    };

    my_animal.bark();
    my_animal.run();

}

Easy Rust Korean 031 ~ 040

Sun, 16 Nov 2025 13:31:19 GMT

031

match 활용!

fn match_colours(rgb: (u32, u32, u32)){
    match rgb{
        (r, _, _) if r < 10 => println!("Not much red!"),
        (_, g, _) if g < 10 => println!("Not much green!"),
        (_, _, b) if b < 10 => println!("Not much blue!"),
        _ => println!("Every colour has at least 10!")
    }
}

fn main(){
    let first = (200, 0, 0);
    let second = (50, 50, 50);
    let third = (200, 50, 0);

    match_colours(first);
    match_colours(second);
    match_colours(third);
}

다음과 같이 여러 type을 혼용해서 사용할 수 없음

fn main(){
    let my_number = 10;
    let some_var = match my_number {
        10 => 8,
        _ => "Not ten"
    };
}

if 를 사용해도 안되는건 마찬가지

fn main(){
    let my_number = 8;
    let some_var = if my_number == 10 {8} else {
        "something else"
    };
}

return 하는 값의 type을 맞추면 가능!

fn main(){
    let my_number = 10;
    let some_var = if my_number == 10 {"ten"} else {
        "else"
    };
    println!("{}", some_var);
}

다음과 같이도 사용 가능

fn match_number(input: i32){
    match input{
        number @ 0..=10 => println!("It's between 0 and 10. Number : {}", number),
        _ => println!("It's greater than ten")
    }
}

fn main(){
    match_number(10);
    match_number(50);
}

032

Struct! (나중에 비슷한 enum 도 있음)

rust에는 3가지 struct가 있음

// unit struct ( 아무것도 없는 구조체 )
struct FileDirectory;

fn main(){
    let x = FileDirectory;
    println!("The size of struct is {}", std::mem::size_of_val(&x)); // size : 0
}

// tuple struct
struct Colour(u8, u8, u8);

fn main(){
    let my_colour = Colour(20, 50, 100);
    println!("The second colour is {}", my_colour.1); 
}

// named struct : 제일 많이 사용됨
struct Country{
    population: u32,
    capital : String,
    leader_name : String
}

fn main(){
    let canada = Country{
        population : 35_000_000,
        capital: "Ottawa".to_string(),
        leader_name: "Justin Trudeau".to_string()
    };

    println!("The population is {}", canada.population);
}

033

Struct Size

struct Country {
    population: u32,
    capital: String,
    leader_name: String
}

fn main(){
    let population = 35_000_000;
    let capital = "Ottawa".to_string();
    let leader_name = "Justin Trudeau".to_string();

    let my_country = Country {
        population,
        capital,
        leader_name
    };
}

-> js와 비슷한 기능!

use std::mem::size_of_val 을 사용해서 struct의 사이즈를 볼 수 있음

use std::mem::size_of_val;

struct Country {
    population: u32,
    capital: String,
    leader_name: String
}

fn main(){
    let population = 35_000_000;
    let capital = "Ottawa".to_string();
    let leader_name = "Justin Trudeau".to_string();

    let my_country = Country {
        population,
        capital,
        leader_name
    };

    println!("Country is {} bytes in size", size_of_val(&my_country));
}

Alignment

use std::mem::size_of_val;

struct Numbers{
    one: u8,
    two: u8,
    three: u8
}

fn main(){
    let my_numbers = Numbers{
        one : 1,
        two : 2,
        three : 3
    };

    println!("Size of struct : {}", size_of_val(&my_numbers));
} // -> size : 3 (bytes)

use std::mem::size_of_val;

struct Numbers{
    one: u8,
    two: u8,
    three: u8,
    four: u32
}

fn main(){
    let my_numbers = Numbers{
        one : 1,
        two : 2,
        three : 3,
        four: 4
    };

    println!("Size of struct : {}", size_of_val(&my_numbers));
} // -> size : 8 (bytes)

왜 size 가 7 이 아닌 8이냐면 러스트가 바이트수를 맞추기 위해........align하는...부분..

034

ENUM

struct 는 and 의 성격 enum 은 or 의 성격

enum ThingsInTheSky{
    Sun, // compiler 가 보기에 0
    Stars // compiler 가 보기에 1
}

fn create_sky_state(time: i32) -> ThingsInTheSky{
    match time{
        6..=18 => ThingsInTheSky::Sun,
        _ => ThingsInTheSky::Stars
    }
}

fn check_sky_state(state: &ThingsInTheSky){
    match state{
        ThingsInTheSky::Sun => println!("I can see the sun"),
        ThingsInTheSky::Stars => println!("I can see the stars"),
    }
}

fn main(){
    let time = 8;
    let sky_state = create_sky_state(time);

    check_sky_state(&sky_state);
}

035

ENUM2 : 간편하게 사용하기

enum Mood{
    Happy,
    Sleepy,
    NotBad,
    Angry
}

fn match_mood(mood: &Mood) -> i32{
    let happiness_level = match mood {
        Mood::Happy => 10,
        Mood::Sleepy => 6,
        Mood::NotBad => 7,
        Mood::Angry => 2
    };
    happiness_level
}

fn main(){
    let my_mood = Mood::NotBad;
    let happiness_level = match_mood(&my_mood);
    println!("Out of 1 to 10, my happiness is {}", happiness_level);
}

이거를 use를 사용해서 쉽게 쓸 수 있음

enum Mood{
    Happy,
    Sleepy,
    NotBad,
    Angry
}

fn match_mood(mood: &Mood) -> i32{
    use Mood::*;
    let happiness_level = match mood {
        Happy => 10, // Mood:: 안써도 됨 
        Sleepy => 6, // Mood:: 안써도 됨 
        NotBad => 7, // Mood:: 안써도 됨 
        Angry => 2 // Mood:: 안써도 됨 
    };
    happiness_level
}

fn main(){
    let my_mood = Mood::NotBad;
    let happiness_level = match_mood(&my_mood);
    println!("Out of 1 to 10, my happiness is {}", happiness_level);
}

enum의 인덱스(?)를 보려면

enum Season{
    Spring, // 0
    Summer, // 1
    Autumn, // 2
    Winter //3
}

fn main(){
    use Season::*;

    let four_seasons = vec![Spring, Summer, Autumn, Winter]; // Vec
    for season in four_seasons {
        println!("The number is: {}", season as u32);
    }
}

036

ENUM3

enum Star{
    BrownDwarf = 10,
    RedDwarf = 50,
    YellowStar = 100,
    RedGiant = 1000,
    DeadStar 
}

fn main(){
    use Star::*;

    let starvec = vec![BrownDwarf, RedDwarf, YellowStar, RedGiant, DeadStar];

    for star in starvec{
        match star as u32{
        size if size <= 80 => println!("Not the biggest star: {}", size),
        size if size >= 80 => println!("Pretty big star: {}", size),
        _ => println!("Some other star")
        }
    };

    println!("What about DeadStar? It is: {}", DeadStar as u32); // 제일 마지막 숫자 + 1
}

enum 이 값을 가지게 할수있음

enum Number{
    U32(u32),
    I32(i32)
}

fn get_number(input: i32) -> Number {
    let number = match input.is_positive(){
        true => Number::U32(input as u32),
        false => Number::I32(input)
    };
    number
}

fn main(){
    let my_vec = vec![get_number(-800), get_number(8)];

    for item in my_vec{
        match item {
            Number::U32(number) => println!("It's a u32 with the value : {}", number),
            Number::I32(number) => println!("It's a i32 with the value : {}", number),
        }
    }
}

037

Loops

기본적인 loop

// rust 스럽지 않은 방법!
fn main(){
    let mut counter = 0;
    loop{
        counter += 1;
        println!("The counter is: {}", counter);
        if counter == 5 {
            break;
        }
    }
}

loop에 이름을 지을 수 있음! (tick 이라고 함)

fn main(){
    let mut counter = 0;
    let mut counter2 = 0;

    'first_loop: loop {
        counter += 1;
        println!("The counter is now: {}", counter);
        if counter > 9 {
            println!("Now entering the second loop");

            'second_loop: loop{
                println!("The second counter is: {}", counter2);
                counter2 += 1;
                if counter2 == 3 {
                    break 'first_loop;
                }
            }
        }
    }
}

038

counter.. 만들어서 하면 rust 적이지 않은 loop!

그럼 어케?

fn main(){
    let mut counter = 0;
    while counter != 5 {
        counter += 1;
        println!("The counter is now: {}", counter);
    }
}

while loop 도 괜찮긴 하지만 제일 많이 사용하는건 for loop

fn main(){
    for number in 0..3 { // 0..3 -> exclusive range!
        println!("The number is {}", number);
    }

    for number in 0..=3 { // 0..3 -> inclusive range!
        println!("The number is {}", number);
    }
}

Easy Rust Korean 021 ~ 030

Sun, 09 Nov 2025 13:35:16 GMT

021

mutable references and mut in function

fn add_is_great(country_name: &mut String){
    country_name.push_str(" is great!");
    println!("Now it says: {}", country_name);
}

fn main(){
    let mut my_country = "캐나다".to_string();

    /*
    add_is_great(my_country); // by value
    add_is_great(&my_country); // by reference
    */
    add_is_great(&mut my_country); // by mutable reference
    add_is_great(&mut my_country);
}

/* Output
Now it says: 캐나다 is great!
Now it says: 캐나다 is great! is great!
*/

비슷하지만 완전 다른 개념!

fn add_is_great(mut country_name: String){ // take by value, declare as mutable
    country_name.push_str(" is great!");
    println!("Now it says: {}", country_name);
}

fn main(){
    let my_country = "대한민국".to_string();
    add_is_great(my_country); // 여기서 소유권이 넘어감!
}

022

Ownership and copy types

fn prints_number(number: i32){
    println!("{}", number);
}

fn prints_string(input: String){
    println!("{}", input);
}

fn main(){
    let my_number = 8;
    prints_number(my_number); // number 는 copy type(copy 하기 쉬움)이라 소유권 신경쓸 필요 없음!
    prints_number(my_number);

    let my_country = "Austria".to_string();
    prints_string(my_country); // 여기서 소유권 넘어감!
    prints_string(my_country); // 그래서 여기서 오류남!

    /*
        오류가 안나게 하려면 .clone 메서드를 사용
        prints_string(my_country.clone());

        clone은 빠르게 컴파일을 하고싶을 때 많이 사용함!
    */

}

023

uninitialized variable & loop

fn main(){
    /*
    let my_number; // 는 불가능!
    */

    /*
    let my_number: i8; // 는 사용은 가능!

    println!("{}", my_number); // 하지만 여기서 에러남!! value가 initialized 되지 않았기 때문
    */

}

fn loop_then_return(mut counter: i32) -> i32 {
    loop {
        counter += 1;
        if counter % 50 == 0 {
            break;
        }
    }
    counter
}

fn main(){
    let my_number;

    {
        let x = loop_then_return(43);
        my_number = x
    }

    println!("{}", my_number); // my_number가 위에서 initialized 됐기 때문에 오류가 발생하지 않음
}

하지만 이 패턴은 잘 안사용! 기존의 코드(C 등등..)을 사용하던 개발자들의 편의를 위해 rust에서 허용하는 기능!

024

Arrays

fn main(){
    let array = ["one", "two"]; // type -> [&str; 2]
    let array2 = ["one", "two", "Five"]; // type -> [&str; 3]]

    // array 와 array2 는 다른 타입이라 비교 자체가 불가능!!
    // array 는 추가할 수 없고, 삭제할 수 없고.. 
}

fn main(){
    let array = ["one", "two"];

    //type을 보기 위한 꼼수 : 존재하지 않는 method 사용 ㅋㅋ
      array.zxcvzxcvasdfasdfasd(); // >> 여기서 [type]에 대한 method 가 없습니다!  라고 에러를 뱉음
}

indexing 은 다른 언어와 비슷!

fn main(){
    let array = ["one", "two"];

    println!("{}", array[0]); // "one" 출력

    /*
        없는 index 출력하면 오류남 !
    */
}

025

Slices

fn main(){
    let seasons = ["봄", "여름", "가을", "겨울"];
    println!("{:?}", seasons[0..2]); // 에러 발생!! dynamically sized type 이라 사이즈를 알 수 없기 때문에 오류가 발생함
}

fn main(){
    let seasons = ["봄", "여름", "가을", "겨울"];
    println!("{:?}", &seasons[0..2]); // reference 를 사용해서 넘길 수 있음!

    /*
        &seasons[0..=2] // up to and including
        &seasons[..] // all
        &seasons[3..] // from 4th index
        &seasons[..4] // up to 5th index
    */
}

026

"누구나 좋아하는" Vecs

= vector

fn main(){
    let my_string = String::new(); // string 선언!
    let mut my_vec: Vec = Vec::new(); 
}

fn main(){
    let name1 = String::from("Windy); 
    let name2 = String::from("Gomesy");

    let mut my_vec = Vec::new();
    // Vec::from() 도 사용가능
    /*
        vec![] 로 더 쉽게 사용가능!

        예를 들어
        let my_vec = vec![name1, name2];
    */

    my_vec.push(name1);
    my_vec.push(name2);

    println!("My cats are {:?}", my_vec);
}

027

Traits = 초능력

fn main(){
    let my_name = String::from("Dave Macleod"); // from 사용!
    let my_city: String = "Seoul".into(); // into 사용!! "Seoul"은 String이 아닌 &str 인데 String 변수에 맞게 변환!?
}

fn main(){
    let my_vec = Vec::from([8,9,10]); // type : [i32; 3]
}

028

tuples : 여러가지 타입을 한 가지 타입으로 표현하고 싶을 때 사용!

fn main(){
    let my_tuple = (8, "Dave MacLeod", vec![8,9,10]);

    my_tuple.asdfasdfasdf(); // 없는 method 로 컴파일러에게 타입 물어보기 ㅋㅋ 
    // -> no method named `asdfasdfasdf` found for tuple `({integer}, &str, Vec<{integer}>)`
    // type : tuple
}

tuple indexing

/*
    Array 와 Vector 에서 indexing 은 array[0], vec[0] 이런식으로 대괄호를 사용해서 인덱싱
    tuple은 대괄호를 사용하지 않고 .0 .1 이런식으로 사용
*/

fn main(){
    let random_tuple = ("Here is a name", 8, vec!['a'], 'b', [8,9,10], 7.7);

    println!("Inside the tuple");
    println!("0 : {:?}", random_tuple.0);
    println!("1 : {:?}", random_tuple.1);
    println!("2 : {:?}", random_tuple.2);
    println!("3 : {:?}", random_tuple.3);
    println!("4 : {:?}", random_tuple.4);
    println!("5 : {:?}", random_tuple.5);
}

여기서 재밌는 점은, Vector의 경우 같은 type의 요소들만 가질 수 있으나 다음과 같이 여러개의 타입을 묶어서 사용할 수도 있음

fn main(){
    let my_vec = vec![("hey",9), ("Hello there", 123123)];
    println!("{:?}", my_vec)
}

Destructuring! -> js의 분해구조할당과 비슷

fn main(){
    let str_tuple = ("one", "two", "three");

    let (a,b,c) = str_tuple;

    println!("Item 'a' is : {}", a);
}

array 도 똑같이 분해 가능!

fn main(){
    let str_array = ["one", "two", "three"];

    let [a,_,_] = str_array; // 관심없는 b, c 대신 _ 사용 가능 -> 워닝 안뜸

    println!("Item 'a' is : {}", a);
}

029

흐름제어

다른언어에서 if 문을 사용할 때 조건은 () 안에 넣는데 러스트는 괄호를 쓸 필요 없음 (에러는 아님)

fn main(){
    let my_number = 5;
    if my_number == 7 {
        println!("It's seven");
    } else if my_number == 6 {
        println!("It's six");
    } else {
        println!("It's a different number");
    }
}

&& || 도 동일하게 사용 가능

fn main(){
    let my_number = 5;
    if my_number == 5 && my_number == 11 {
        println!("Both are matched");
    } else if my_number == 5 || my_number == 11 {
        println!("my number is 5 or 11");
    } else {
        println!("It's a different number");
    }
}

하지만 이것보다 더 자주 쓰이는건 "match"

-> switch 와 비슷

fn main(){
    let my_number: u8 = 5;

    match my_number{
        0 => println!("It's a zero"),
        1 => println!("It's a one")
    }
} //=>에러남. u8 은 256까지 가능한데 나머지에 대한 정의가 안돼있기 때문

fn main(){
    let my_number: u8 = 5;

    match my_number{
        0 => println!("It's a zero"),
        1 => println!("It's a one"),
        _ => println!("Other number"); // _ 기호를 사용해서 나머지 타입(else)에 대한 정의
    }
}

match 로 변수에 값을 할당할 수도 있음

fn main(){
    let my_number: u8 = 5;

    let my_second_number = match my_number{
        0 => 23,
        1 => 34,
        _ => 0
    };

    println!("{}", my_second_number);
}

030

tuple 활용

여러개의 변수를 한번에 비교할 수도 있음!

fn main(){
    let sky = "cloudy";
    let temperature = "warm";

    match (sky, temperature){
        ("cloudy", "cold") => println!("It's not very nice day"),
        ("cloudy", "warm") => println!("It's a nice day"),
        ("cloudy", _) => println!("Cloudy and something else"),
        _ => println!("Not sure what the weather is")
    }
}

조건문도 사용 가능

fn main(){
    let children = 5;
    let married = true;

    match(children, married){
        (children, married) if married == false => println!("Not married with {} children", children),
        (c,m) if c==0 && m => println!("Married but with no children"),
        _ => println!("Some other type of marriage and children combination")
    }
}

Easy Rust Korean 011 ~ 020

Sun, 09 Nov 2025 13:35:11 GMT

011

mutability & shadowing

mutability : 변경가능여부

기본적으로 immutable (변수 선언 시 기본적으로 변경 불가능)

fn main(){
    let my_number = 10;
    my_number = 9;
}

>>> ERROR

my_number 는 immutable 이기 때문에 에러 발생 이 경우 mut 키워드를 사용해서 변경가능할 수 있게 해줘야함

fn main(){
    let mut my_number = 10;
    my_number = 9;
}

mut 키워드를 사용하고나서 변경되지 않았다면, 컴파일러가 이를 알려주고, mut 키워드 삭제 가능

shadowing : 같은 이름을 다시 쓰는 것

fn main(){
    let my_variable = 10;
       let my_variable = "My Variable";
}

// -> my_variable 은 마지막에 작성된 "My Variable"만 값으로 생각함.

왜 사용? 코딩을 하면서 필요한 값은 최종 결과인데, 이를 위한 여러 변수들이 불필요하게 선언될 필요 없음

fn double(input: i32) -> i32 {
    input * 2
}

fn triple(input: i32) -> i32 {
    input * 3
}

fn main(){
    let x_origin = 9;
       let x_double = double(x_origin);
    let x_final = triple(x_double);

    println!("{}", x_final);
}

// -> 결과적으로 필요한 값은 xFinal 인데, xOrigin, xDouble 같은 변수가 선언됨

//-----------Shadowing 으로 다음과같이 사용할 수 있음-----------
fn main(){
    let x = 9;
       let x = double(x);
    let x = triple(x);

    println!("{}", x);
}

CodeBlock 을 이용해서 Shadowing을 다양하게 활용할 수 있음

fn main(){
    let my_var = 9;
    {
        let my_var = "Some String";
        println!("{}", my_var); // Some String 출력
    }
    println!("{}", my_var); // 9 출력
}

012

Stack / heap / pointers

Stack Memory

먼저 들어온 Task가 다음에 들어온 Task가 종료될때까지 기다리는 메모리 구조. Task가 종료되면 할당받은 Memory 는 반환

Heap Memory

창고같은 곳에서 "어디로 가면 어떤 물건이 있어요" 같이 동작하는 메모리 구조. 비교적 속도가 느리지만 많은 용량을 저장할 수 있음.

Pointers

아래와 같이 어떤 내용이 어디에 있는지 알려주는 역할

Chapter
Chapter 1: My life, Page : 1 
Chapter 2: My life, Page : 15
Chapter 3: My life, Page : 23

Rust에서는 Pointer를 Reference 라고 부름. reference 를 사용할 때에는 "&" 기호를 사용함.

fn main(){
    let my_number = 15; // 값. i32
    let single_reference = &my_number; // my_number 에 대한 싱글 레퍼런스. &i32
    let double_reference = &single_reference; // my_number 에 대한 레퍼런스에 대한 레퍼런스. &&i32

    let five_references = &&&&&my_number; // 이것도 사용 가능. 
}

싱글레퍼런스, 더블레퍼런스, 모두 다른 타입이기 때문에 상호 비교가 불가능!!

013

Fancy Printing : print!() 사용

아래 두 줄의 문장은 같은 동작을 함

println!(message); print!("{}\n",message);

예를들면

fn main(){
    //#1
    println!("This");
    println!("is");
    println!("a");
    println!("message");

    //#2
    print!("This\n");
    print!("is\n");
    print!("a\n");
    print!("message\n");

    //#3
    print!("This\nis\na\nmessage\n");
}

위의 1, 2, 3번 코두 동일한 동작을 함

Output : 

This
is
a
message

\n 이라는 기호를 출력하고 싶다면? -> \\n 사용

fn main(){
    print!("This \\n is a message"); // Output : This \n is a message
}

그런데 \를 너무 많이 써야하는 상황이라면? 예를들어 다음 디렉토리를 표시하려면 c:\drive_a\new_drive\path_name

코드는 다음과 같이 안예뻐질 것

fn main(){
    print!("c:\\drive_a\\new_drive\\path_name");
}

이럴때 사용하는것이 "Raw Text" 다음과 같이 사용할 수 있다.

fn main(){
    print!(r#"c:\drive_a\new_drive\path_name"#);
}

줄바꿈을 다음과같이 사용할 수도 있는데

fn main(){
    println!("Let me tell you 
    some story
    about
    rust");
}

출력이 다음과 같다.

Let met tell you
    some story
    about
    rust

앞에 인덴트가 있기 때문에 그런것! 주의하여 사용할 것

전에 Debug Print 에 대해 잠시 다뤘는데

println!("{:?}", var_name);

으로 사용했다.

왜 물음표로 사용하냐면 어떤 타입이든 출력을 하기 때문.

특정 data type을 출력하기 위해선 다음과 같은 format을 사용한다

fn main(){
    let my_number = 9000;
    println!("{:p}", &my_number); // reference(pointer) 출력
    println!("{:X}", my_number); // Hex값 출력
    println!("{:b}", my_number); // Bytes값 출력

    println!("{:p}", my_number); // 는 오류 : p는 포인터 data type을 출력한다고 하는데, my_number 는 값이기 때문에
}

이 포맷을 조금 더 다양하게 활용이 가능하다.

fn main() {
    let title = "TODAY'S NEWS";
    println!("{:-^30}", title); // no variable name, pad with -, put in centre, 30 characters long
    let bar = "|";
    println!("{: <15}{: >15}", bar, bar); // no variable name, pad with space, 15 characters each, one to the left, one to the right
    let a = "SEOUL";
    let b = "TOKYO";
    println!("{city1:-<15}{city2:->15}", city1 = a, city2 = b); // variable names city1 and city2, pad with -, one to the left, one to the right
}

Output:

---------TODAY'S NEWS---------
|                            |
SEOUL--------------------TOKYO

더 많은 내용은 아래 링크 참고 https://doc.rust-lang.org/stable/std/fmt/

014

Strings

String / &str 을 주로 사용

fn main(){
    let my_name = "David"; // &str
    let other_name = String::from("David2");

    /*
    let my_other_name = "David3"; // &str
    my_other_name.push("!"); // 여기서 에러 발생!  &str 에는 .push 가 없기 때문
    */


    // 다음과 같이 하면 오류 발생 안함
    let my_other_name = "David3".to_string(); // String
    my_other_name.push("!");


    println!("{}", my_other_name);
}

String type 은 Sized type str = dynamic type -> 길이를 컴파일러가 알 수 없음 => &str을 사용

015

&str 보다 String 이 사용하기 더 쉬운 이유!

method 사용이 용이함

.push : 한 글자 추가 .push_str : &str 추가 .capacity : 바이트 크기 .pop : with_capacity : 바이트 크기 명시하여 String 선언

let mut my_name = "David".to_string();
my_name.push('!');
println!("My name is {}", my_name);

let mut my_name = String::with_capacity(26);
println!("Length is {} and capacity is {}", my_name.len(), my_name.capacity());
my_name.push_str("David!");
println!("Length is {} and capacity is {}", my_name.len(), my_name.capacity());
my_name.push_str("And I live in Seoul");
println!("Length is {} and capacity is {}", my_name.len(), my_name.capacity());
my_name.push('a');
println!("Length is {} and capacity is {}", my_name.len(), my_name.capacity());

/* Output : 
Length is 0 and capacity is 26
Length is 6 and capacity is 26
Length is 25 and capacity is 26
Length is 26 and capacity is 26
*/

016

const / static

fn main(){
    let x = 8; // 'let' binding 이라고 함
}

const는 Global 변수를 선언함

const NUMBER: i32 = 20; // const 선언 변수명은 대문자로(소문자로 쓰면 warning), 타입 지정은 필수!

fn main(){
    let x = 8; // 'let' binding 이라고 함
}

static도 const와 비슷

const NUMBER: i32 = 20; // const 선언 변수명은 대문자로(소문자로 쓰면 warning), 타입 지정은 필수!
static LOW_SCORE: i32 = 0;

/*
static 은 mut 를 통해 unsafe 를 사용할 수는 있으나 거~~의 안씀!!

static mut LOW_SCORE: i32 = 0;
*/

fn main(){
    let x = 8; // 'let' binding 이라고 함
}

017

OWNERSHIP

fn main(){
    let country = String::from("대한민국");
    let ref_one = &country;
    let ref_two = &country;

    println!("Country is: {}", ref_one);
}

fn return_it() -> &String {
    let country = String::from("대한민국");
    &country // ref 반환
}

fn main(){
    let my_country = return_it(); // >> 오류!!
}

018

mutable references

& -> immutable reference / shared reference &mut -> mutable reference / unique reference

fn main(){
    let mut my_number = 9;
    let num_ref = &mut my_number;

    /* 이렇게 코딩하면 오류남!! 
    num_ref = 10;
    */

    *num_ref = 10; // &의 반대개념 *

    // && 이면 ** 사용!
    /*
        let num_ref = &mut &mut my_number;
        **num_ref = 10;
    */
}

019

references and shadowing

// 오류 반환됨!!
fn main(){
    let mut number = 10;
    let number_ref = &number;
    let number_change = &met number;
    *number_change += 10;
}

// 정상 작동됨
fn main(){
    let mut number = 10;
    let number_change = &met number;
    *number_change += 10;
    let number_ref = &number;
}

shadowing!

// 정상 작동됨
fn main(){
    let country = "대한민국";
    let country_ref = & country;
    let country = 8; // shadowing

    println!("{}, {}", country_ref, country); 
    // -> "대한민국" 이 없어지지 않았음을 확인할 수 있음!"
}

020

OWNERSHIP

fn print_country(country_name: String){
    println!("My country is {}", country_name);
}

fn main(){
    let country = "대한민국".to_string();
    print_country(country); // 여기서 country 의 소유권이 print_country 함수로 넘어감
    print_country(country); // 여기서 에러 발생!!
}

fn print_country(country_name: &String){
    println!("My country is {}", country_name);
}

fn main(){
    let country = "대한민국".to_string();
    print_country(&country); // 여기서 country 의 소유권은 넘어가지 않음!
    print_country(&country); // 에러 발생 X!
}

Easy Rust Korean 001 ~ 010

Sun, 26 Oct 2025 02:26:27 GMT

001

웹 IDE (rust전용)

https://play.rust-lang.org

permalink to the playground : 코드를 포함한 ide 링크 복사가능

Rust 의 장단점

장점

c, c++ 처럼 빠른속도

단점

어려움

002

comments (주석)

가장 기본적인 주석

// This is normal comment

Documentation 주석

/// This is normal comment

부분적인 주석

fn main() {
    let x/*: i16*/ = 10;
}

사용하지 않은 변수에 대해 언더스코어(_) 로 이름을 시작하게 되면 미사용변수에 대한 Warning 이 없음

003

Primitive types : 기본 데이터 타입

integer (정수, 음수 가능)

i8, i16, i32, i64, i128, and isize

unsigned integer (부호없는 정수, 음수 불가능)

u8, u16, u32, u64, u128, and usize

(i -> integer || u -> unsigned) + bit 수 로 표현

let my_number = 100;

변수 선언 시 let 사용

my_number 는 어떤 타입인지 알 수 없음

-> u8타입을 지정하고 싶다면 다음과 같이 지정 가능

let my_number: u8 = 100;

type inference

다음과 같은 코드에서는 컴파일러가 타입을 추론하여 계산함

let my_number: u8 = 100; 
let my_other_number = 50; // type 미지정, 기본 : i32(or i64)
let _third_number = my_number + my_other_number;

u8 + i64 연산은 기본적으로 안되지만, my_other_number 에 대해 타입지정을 안했기 때문에 컴파일러가 타입을 추론하여 연산할 수 있음.

다음과 같이 각 변수에 대해 타입이 지정돼있는 변수사이의 연산은 불가능

let my_number: u8 = 100; 
let my_other_number: u16 = 50; // u16 지정
let _third_number = my_number + my_other_number;

>> ERROR

004

Char

println!(String); 의 형태에서는 무조건 큰 따옴표 ("")를 사용하고, Char type 변수를 선언할 때에는 작은 따옴표 ('')를 사용

String : 문자열 Char : 문자

char type은 4bytes 크기

println!("Hello, world!");
let first_letter = 'A';
let space = ' ';

Casting

simple type change using 'as'

let my_number: u16 = 8;
let second_number: u8 = 10;
let third_number = my_number + second_number as u16;

Char -> u8 으로 캐스팅 하면 ASCII Code 가 됨

let my_number = 'a' as u8;
println!("Hello, world! My number is {}", my_number);

005

Char 와 String의 차이

Char type 의 크기는 4bytes

println!("Size of a char: {}", std::mem::size_of::()); // 4bytes

Sring ("")타입의 크기는 .len()으로 알 수 있음

println!("Size of string containing 'a': {}", "a".len()); // 1 출력 = 1byte

글자수와 비슷하지만, 사실 글자수가 아닌 bytes 수

println!("Size of string containing 'ß': {}", "ß".len()); // 독일어 : 2bytes
println!("Size of string containing '国': {}", "国".len()); // 한자 : 3bytes
println!("Size of string containing '𓅱': {}", "𓅱".len()); // 고대 이집트어 : 4bytes

string의 bytes수가 아닌 글자수를 알려면?

.chars().count() 사용

let slice = "Hello!";
println!("Slice is {} bytes and also {} characters.", slice.len(), slice.chars().count());

// .chars() : "Hello!" -> 'H', 'e', 'l', ... , '!';

006

숫자형 (u8, u16, ...) 앞에 숫자를 넣어서 변수선언과 타입지정을 한번에 할 수 있음

// 중간에 underscore(_)는 아무리 많이 써도 상관없음
let my_number = 9_u8; // u8 타입의 9값을 가진 변수
let second_number = 1_000_000_000u64; 
let third_number = 9_____________1u32;

Float

let float_number = 9.;

f32 / f64 로 타입지정(주로 f64사용)

let f_number = 9.; // f64
let s_number: f64 = 1.1;
let t_number = 8; // i32
println!("{}", f_number + s_number + t_number as f64); // 18.1

007

println!()

-> println meand print line -> ! means macro

매크로는 super function.

변수 사용({})기호를 사용하고 변수할당을 하지 않으면 에러 발생

let my_name = "David";
println!("My name is {}");

>> ERROR

function

fn func_name() -> return_type {
}

형식으로 함수 선언 가능

fn give_age() -> i32 {
    42 // return 42 라고 하지 않아도 됨!
}

fn main(){
    let my_name = "David";
    println!("My name is {} and my age is {}", my_name, give_age());
}

008

println!() - 2

{} 안에 변수명을 넣어서 사용 가능!

fn main(){
    let my_city = "Seoul";
    let year = 2002;
    let population = 9_987_987;
    println!("The city of {city} in {year} had a population of {population}",
    city = my_city,
    year = year,
    population = population);
}

{} 안에 변수 인덱스를 넣어서 사용 가능!

fn main(){
    let my_city = "Seoul";
    let year = 2002;
    let population = 9_987_987;
    println!("The city of {0} in {1} had a population of {2}. I love {0}",
    my_city,
    year,
    population);
}

string interpolation

fn main(){
    let city = "Seoul";
    let year = 2002;
    let population = 9_987_987;
    println!("The city of {city} in {year} had a population of {population}. I love {city}");
}

다음과 같이 expression(표현식)은 사용 불가능

fn main(){
    let city = "Seoul";
    let year = 2002;
    let population = 9_987_987;
    println!("The city of {city} in {year+2} had a population of {population}. I love {city}");
}

>> year+2 에서 Error

009

empty tuple

// 8을 반환하는 함수 number()
fn number() -> i32 {
    8
}

하지만 8 뒤에 세미콜론을 붙이게 된다면 에러 발생

// 8을 반환하는 함수 number()
fn number() -> i32 {
    8;
}

fn main() {
    let my_number = number();
}

/*
>> Error : expected i32 but found ()
() 는 Rust 에서 empty tuple, unit type 이라고 부르고 다른 언어에서는 void 라고 부름
*/

Display, Debug

Display : {}
Debug Print : {:?}

fn empty_tuple() {
}

fn main() {
    let tuple = empty_tuple();
    println!("{}", tuple); // error
    println!("{:?}", tuple); // 웬만해서는 출력 가능!
}

010

function

앞서 알아본 간단한 함수의 모양은 다음과 같음

fn give_number() -> i32 {
    8
}

fn main() {
    let my_number = give_number();
}

Parameter 를 받아서 반환하는 형태의 함수는 다음과 같음

fn give_number(one: i32, two: i32) -> i32 {
    one * two
}

fn main() {
    let my_number = give_number(9,8);
    println!("{}", my_number);
}

Code block 활용

fn give_number(one: i16, two: i16) -> i16 {
    let multiplied_by_ten = {
        let f_number = 10;
        f_number * one * two
    };
    multiplied_by_ten
}

fn main() {
    let my_number = give_number(9,8);
    println!("{}", my_number);
}

강의 링크 https://youtube.com/playlist?list=PLfllocyHVgsSJf1zO6k6o3SX2mbZjAqYE&si=LfVF7DHgzWT7iUrp

Grafana 대시보드 설정

Thu, 03 Apr 2025 06:53:36 GMT

최종 결과 대시보드!

대시보드 구성

Node Exporter

시스템 리소스 정보(CPU, 메모리, 디스크, 네트워크 등)를 HTTP endpoint로 제공

localhost:9100/metrics 로 시스템 리소스 정보를 제공

Prometheus

다양한 지표를 수집하고 저장하는 시스템

대상(예 : node-exporter) 에 주기적으로 접근하여 메트릭 데이터를 가져옴

Grafana

메트릭 데이터를 불러와 대시보드 형태로 시각화해주는 툴

관계 요약

Element	역할
Node Exporter	메트릭 데이터 제공
⬇️
Prometheus	데이터 수집 및 저장
⬇️
Grafana	데이터 시각화

설치 & 실행 & 설정

OS : Ubuntu, sudo su 로 관리자 계정에서 진행합니다.

Node Exporter

https://prometheus.io/download/#node_exporter

리눅스 버전의 다운로드 링크를 복사합니다.

wget 명령어를 통해서 압축파일을 다운받습니다.

wget https://github.com/prometheus/node_exporter/releases/download/v1.9.0/node_exporter-1.9.0.linux-amd64.tar.gz

압축파일 다운로드가 완료되었다면 아래 명령어로 파일이 존재하는지 확인합니다.

ls node_exporter*

파일이 존재한다면 압축을 풀어준 뒤, 압축해제된 경로로 이동합니다.

tar xzvf node_exporter-1.9.0.linux-amd64.tar.gz
cd node_exporter-1.9.0.linux-amd64

ls 명령어로 디렉토리의 파일 목록을 확인하면 다음과 같습니다

이제 node_exporter 파일을 /usr/local/bin 폴더로 옮겨줍니다.

mv node_exporter /usr/local/bin

파일을 옮겼다면, 시스템 서비스 등록을 합니다.

vim /etc/systemd/system/node-exporter.service

아래 내용을 복사 붙여넣기 한 뒤 저장합니다.

[Unit]
Description=Node Exporter
After=network.target

[Service]
User=nobody
ExecStart=/usr/local/bin/node_exporter

[Install]
WantedBy=default.target

서비스를 시작하고, 부팅 시 자동 실행하도록 설정합니다.

systemctl daemon-reexec
systemctl daemon-reload
systemctl start node-exporter
systemctl enable node-exporter

아래 명령어를 통해 시스템이 정상작동하고 있는지 확인합니다.

systemctl status node-exporter

curl http://localhost:9100/metrics

Prometheus

node-exporter 설정이 끝났으니 prometheus 를 설치해 봅니다.

먼저, Prometheus 시스템 그룹을 생성합니다.

groupadd --system prometheus

prometheus 사용자를 추가하고, 생성된 그룹에 할당해 줍니다.

useradd -s /sbin/nologin --system -g prometheus prometheus

그리고 prometheus를 위한 디렉토리를 생성해 줍니다.

mkdir /etc/prometheus

다음으로 아래 링크에 들어가서 프로메테우스 다운로드 링크를 복사합니다.

https://prometheus.io/download/#prometheus

LTS 버전을 받도록 하겠습니다.

wget 명령어를 통해서 압축파일을 다운받습니다.

wget https://github.com/prometheus/prometheus/releases/download/v2.53.4/prometheus-2.53.4.linux-amd64.tar.gz

압축파일을 풀어준 뒤 압축이 해제된 디렉토리로 이동해줍니다.

tar xzvf prometheus*.tar.gz
cd prometheus*/

해당 폴더에 있는 prometheus 바이너리 파일을 옮겨준 뒤 버전을 확인합니다.

mv prometheus promtool /usr/local/bin/
prometheus --version

그럼 이제 아까 만들어둔 prometheus 폴더에 구성 파일을 옮겨줍니다.

mv prometheus.yml /etc/prometheus/prometheus.yml
mv consoles/ console_libraries/ /etc/prometheus/

파일을 옮긴 뒤 구성파일의 내용을 확인해 줍니다.

cat /etc/prometheus/prometheus.yml

이제 프로메테우스 시스템을 등록합니다.

vim /etc/systemd/system/prometheus.service

위 명령어로 에디터를 열어서, 아래 내용을 붙여넣어 줍니다.

[Unit]
Description=Prometheus
Documentation=https://prometheus.io/docs/introduction/overview/
Wants=network-online.target
After=network-online.target
[Service]
User=prometheus
Group=prometheus
Type=simple
ExecStart=/usr/local/bin/prometheus \
--config.file /etc/prometheus/prometheus.yml \
--storage.tsdb.path /var/lib/prometheus/ \
--web.console.templates=/etc/prometheus/consoles \
--web.console.libraries=/etc/prometheus/console_libraries \
--web.listen-address=0.0.0.0:9090 \

[Install]
WantedBy=multi-user.target

/var/lib/prometheus/ 디렉토리를 storage path 로 설정해 놓았기 때문에, 해당 디렉토리를 생성하고, 권한을 부여합니다.

mkdir /var/lib/prometheus
chown -R prometheus:prometheus /var/lib/prometheus

이제 prometheus 설정은 끝났으니 실행시켜 봅니다.

systemctl daemon-reload
systemctl start prometheus
systemctl enable prometheus

잘 작동하고 있음을 확인할 수 있습니다.

node-exporter <> prometheus 연동

Prometheus 의 설정파일을 수정해줍니다.

vim /etc/prometheus/prometheus.yml

최하단에 있는 scrape_configs: 부분에 아래 내용을 추가해 줍니다.

- job_name: 'node-exporter'
    static_configs:
      - targets: ['localhost:9100']

prometheus를 재시작 하고, 연동이 잘 되었는지 확인합니다.

systemctl restart prometheus
curl http://localhost:9090/api/v1/targets

activeTargets 에 localhost:9100/metrics 가 있는지 확인합니다.

Grafana

먼저 apt 업데이트를 진행한 뒤, 필요 패키지를 다운받습니다.

apt update -y && sudo apt upgrade -y
apt install -y apt-transport-https software-properties-common wget

Grafana GPG 키를 추가해주어야 합니다.

아래 명령어를 통해 GPG 키를 다운받아 줍니다.

sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null

Grafana APT 저장소를 추가해 준 뒤 grafana 를 설치해 줍니다.

echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee -a /etc/apt/sources.list.d/grafana.list
apt update
apt install grafana

설치가 완료되었다면 제대로 설치가 되었는지 확인하고, 서비스를 시작합니다.

grafana-server -v

systemctl start grafana-server
systemctl enable grafana-server

systemctl status grafana-server

잘 동작하고 있는것을 확인할 수 있습니다.

grafana 가 동작하는 3000번 포트를 개방하고 접속해보겠습니다.

최초 자격증명은 admin/admin 입니다.

비밀번호를 변경하라는 창이 뜹니다만 skip 하겠습니다.

먼저 데이터 소스를 추가해 주겠습니다.

프로메테우스 클릭

connection 에는 http://localhost:9090 을 입력해줍니다.

제일 밑에 save&test를 누르면 쿼리에 성공했다는 메세지가 나옵니다.

그렇다면 다시 홈으로 돌아와서 dashboard 설정을 해보겠습니다.

우측 상단의 + 버튼을 누르고 import dashboard를 클릭

node exporter 기본 템플릿을 불러옵니다.

데이터 소스를 프로메테우스로 선택해주면

대시보드 설정 완료입니다.

Multicall Contract

Sun, 17 Nov 2024 11:52:08 GMT

MultiCall 이란?

여러개의 트랜잭션을 한번에 전송할 수 있게 도와주는 컨트랙트입니다.

장점

여러개의 트랜잭션을 한번에 묶어서 보내기 때문에 각각의 트랜잭션을 전송하는것 보다 가스비가 저렴할 수 있습니다.
트랜잭션에 대해 서명을 한 번만 하면 되기 때문에, UX향상을 기대할 수 있습니다.

Multicall 컨트랙트 주소

웬만한 네트워크에는 배포되어있는듯 합니다. 신기하게도 모든 네트워크에 배포된 컨트랙트 주소가 동일합니다

https://www.multicall3.com/deployments

Multicall Abi

아래 링크에서 확인할 수 있습니다.

https://www.multicall3.com/abi#json

사용법

여러개의 contract 에서 read 함수를 호출하여 결과를 종합하는 경우
여러개의 상태가 변경되는 함수를 호출하는 경우

🍏여러개의 contract 에서 read 함수를 호출하여 결과를 종합하는 경우

callData를 생성

 // callData 형식
 struct {
     target : contractAddress,
     callData : contract.interface.encodeFunctionData("methodName", [param1, param2, ...]
 }

 // contract instance 에서 functionData encoding
 const mulltiCallData = [
     {
         target : contractAddress1,
         callData : contract1.interface.encodeFunctionData("methodName1", [param1, param2, ...]
     },
     {
         target : contractAddress2,
         callData : contract2.interface.encodeFunctionData("methodName2", [param1, param2, ...]
     },
 ]

 // contractInterface instance 에서 functionData encoding
 const contractInterface1 = new ethers.Interface(ABI1)
 const contractInterface2 = new ethers.Interface(ABI2)

 const mulltiCallData = [
     {
         target : contractAddress1,
         callData : contractInterface1.encodeFunctionData("methodName1", [param1, param2, ...]
     },
     {
         target : contractAddress2,
         callData : contractInterface2.encodeFunctionData("methodName2", [param1, param2, ...]
     },
 ]

aggregate 함수 호출

 // ethers.js v6 기준!

 const multicallResultRaw = await multicallContract.aggregate.staticCall(multiCallData)

호출결과를 decoding

 /*
 aggregate 반환값 형식 = [blockNumber , [ Result1, Result2, Result3, ... ]
 */

 // contract instance 에서 functionDataResult decoding
 const [ blockNum, results ] = multicallResultRaw
 const [ result1, result2 ] = [
     contract1.interface.decodeFunctionResult("methodName1",results[0]),
     contract2.interface.decodeFunctionResult("methodName2",results[1]),
 ]

 // contractInterface instance 에서 functionDataResult decoding
 const [ result1, result2 ] = [
     contractInterface1.decodeFunctionResult("methodName1",results[0]),
     contractInterface2.decodeFunctionResult("methodName2",results[1]),
 ]

코드예시

  async function main() {
    const rpcUrl = "https://api.avax-test.network/ext/bc/C/rpc";
    const provider = new ethers.JsonRpcProvider(rpcUrl);
    const multicallContractAddress = "0xcA11bde05977b3631167028862bE2a173976CA11";

    const multicallContract = new ethers.Contract(
      multicallContractAddress,
      multicallAbi,
      provider
    );

    const token0Address = "0x2B4931ab37d33AE909d605476168F90E10C1A9e4";
    const token1Address = "0xb13BebA6d96244C38dcbcbd448303351BaF7723c";

    const tokenInterface = new ethers.Interface(tokenAbi);

    const multiCallData = [
      {
        target: token0Address,
        callData: tokenInterface.encodeFunctionData("name"),
      },
      {
        target: token0Address,
        callData: tokenInterface.encodeFunctionData("symbol"),
      },
      {
        target: token1Address,
        callData: tokenInterface.encodeFunctionData("name"),
      },
      {
        target: token1Address,
        callData: tokenInterface.encodeFunctionData("symbol"),
      },
    ];

      // only call once
    const [, [token0NameRaw, token0SymbolRaw, token1NameRaw, token1SymbolRaw]] =
      await multicallContract.aggregate.staticCall(multiCallData);

    const [token0Name] = tokenInterface.decodeFunctionResult(
      "name",
      token0NameRaw
    );
    const [token0Symbol] = tokenInterface.decodeFunctionResult(
      "symbol",
      token0SymbolRaw
    );
    const [token1Name] = tokenInterface.decodeFunctionResult(
      "name",
      token1NameRaw
    );
    const [token1Symbol] = tokenInterface.decodeFunctionResult(
      "symbol",
      token1SymbolRaw
    );

    console.log(token0Name);
    console.log(token0Symbol);
    console.log(token1Name);
    console.log(token1Symbol);
  }

🍏여러개의 contract 에서 state-changing 함수를 호출하여 결과를 종합하는 경우

callData를 생성

 // callData 형식
 struct {
     address target;
     bool allowFailure; // false 일 경우 해당 callData 호출 실패시, 전체 트랜잭션이 revert됨
     bytes callData;
 }

 // contract instance 에서 functionData encoding
 const mulltiCallData = [
     {
         target : contractAddress1,
         allowFailure : true,
         callData : contract1.interface.encodeFunctionData("methodName1", [param1, param2, ...]
     },
     {
         target : contractAddress2,
         allowFailure : false,
         callData : contract2.interface.encodeFunctionData("methodName2", [param1, param2, ...]
     },
 ]

 // contractInterface instance 에서 functionData encoding
 const contractInterface1 = new ethers.Interface(ABI1)
 const contractInterface2 = new ethers.Interface(ABI2)

 const mulltiCallData = [
     {
         target : contractAddress1,
         allowFailure : true,
         callData : contractInterface1.encodeFunctionData("methodName1", [param1, param2, ...]
     },
     {
         target : contractAddress2,
         allowFailure : false,
         callData : contractInterface2.encodeFunctionData("methodName2", [param1, param2, ...]
     },
 ]

aggregate3 함수 호출

 // ethers.js v6 기준!

 const tx = await multicallContract.connect(wallet).aggregate3(multiCallData)
 await tx.wait()

코드예시

  const multicallData2 = [
      {
        target: token0Address,
        allowFailure: true,
        callData: tokenInterface.encodeFunctionData("faucet", [tokenAmount]),
      },
      {
        target: token0Address,
        allowFailure: true,
        callData: tokenInterface.encodeFunctionData("transfer", [
          wallet.address,
          tokenAmount,
        ]),
      },
      {
        target: token1Address,
        allowFailure: true,
        callData: tokenInterface.encodeFunctionData("faucet", [tokenAmount]),
      },
      {
        target: token1Address,
        allowFailure: true,
        callData: tokenInterface.encodeFunctionData("transfer", [
          wallet.address,
          tokenAmount,
        ]),
      },
    ];

    const tx = await multicallContract.connect(wallet).aggregate3(multicallData2);

    await tx.wait();

    const token0BalanceAfter = await token0Contract.balanceOf(wallet.address);
    const token1BalanceAfter = await token1Contract.balanceOf(wallet.address);

    console.log(
      `Token0 Balance : ${ethers.formatEther(
        token0BalanceBefore
      )} -> ${ethers.formatEther(token0BalanceAfter)}`
    );

    console.log(
      `Token1 Balance : ${ethers.formatEther(
        token1BalanceBefore
      )} -> ${ethers.formatEther(token1BalanceAfter)}`
    );

💡multicall 을 통해 함수를 실행할 때 주의해야할 점

msg.sender 가 multicall contract Address 가 되기 때문에 transfer, approve같은 메서드를 호출할 때 메서드 실행주체에 대해 잘 생각해야함.

실행결과 tx 정보 확인 → https://testnet.snowtrace.io/tx/0x3395ec1e1888acc7e91f78f4b4969f6cde93e43d881fc37086f80bc8c2d8a94d/internal?chainid=43113

Multicall Contract 와 import 된 Multicall 차이점

Multicall Contract

Multicall Contract 를 통해 tx 를 전송하게 될 경우 구조는 다음과 같습니다.

[ Wallet ] → [ Multicall Contract ] → [ Target Contract ]

따라서 Target Contract 입장에서 tx의 주체, 즉 msg.sender 는 Multicall Contract가 됩니다.

상황 예시

내 지갑(W0)에 90 TokenA 가 있다.
(W1, W2, W3) 에 30 TokenA 씩 전송하려고 한다.
( token.transfer ) 트랜잭션 3개를 multicall로 전송한다.
multicall은 3개의 트랜잭션을 TokenA 컨트랙트로 전송한다.
이때, transfer의 호출 주체(msg.sender) 는 multicall contract 이고, multicall contract 는 tokenA 잔액이 0 이기 때문에 모든 트랜잭션이 revert 된다.

코드를 살펴보면, multicall Contract 가 target Contract로 callData 를 그대로 전송하고 있습니다.

import 된 Multicall

위 사진과 같이 Multicall 을 상속받는 경우는 조금 다른 부분이 있습니다.

위 코드에서 상속받은 Multicall 코드를 살펴보면 다음과 같이 작성돼있습니다.

여기서는 delegatecall 을 사용하여 tx를 처리하고 있음을 확인할 수 있습니다.

delegateCall 은 특정 함수를 호출할 때 msg.sender 와 msg.value를 그대로 유지하여 트랜잭션을 전송하게 됩니다.

상황 비유

예시 상황으로 두 방법에 대해 정리하자면,

상황 : 사람A 가 사람B 에게 중간 매개자(사람C)를 통해 물건을 전송하는 상황.

Multicall Contract를 사용한다면
1. 사람A 가 사람C에게 물건을 전달한다. 물건에는 [보낸 사람 : 사람A] 라고 적혀있다.
2. 사람C 가 사람B에게 물건을 전달한다. 물건에는 [보낸 사람 : 사람C] 라고 적혀있다.
import된 Multicall 을 사용한다면
1. 사람A 가 사람C에게 물건을 전달한다. 물건에는 [보낸 사람 : 사람A] 라고 적혀있다.
2. 사람C 가 사람B에게 물건을 전달한다. 물건에는 [보낸 사람 : 사람A] 라고 적혀있다.

정리

Multicall Contract
- "한번에" 여러개의 target Contract로, 여러개의 트랜잭션을 보낼 수 있는것
- 트랜잭션의 주체가 multicall Contract
import된 Multicall
- 한번에 여러개의 트랜잭션을 보낼 수 있지만, target Contract는 해당 컨트랙트로만 한정
- 트랜잭션의 주체가 wallet(caller)

UniswapV2 동작 이해하기 (1)

Tue, 04 Jun 2024 15:17:36 GMT

Uniswap V2 란?

CPMM

uniswapV2 에서는 CPMM (Constant Product Market Maker)을 사용합니다. 다른건 몰라도 이것만 알면 됩니다.

x * y = k

뭔가 복잡해보이는 이름에 걸맞지 않는 간단한 수식입니다. 매우 간단해 보여도 uniswapV2의 핵심이 되는 수식이니 잘 이해해야합니다. 위의 수식이 어떻게 사용되는지 예시를 통해 알아봅시다.

유동성(Liquidity)

유동성이란 거래를 위해 사용될 수 있는 자산을 의미합니다.

Swap

swap은 "교환"과 같은 의미입니다.

사과를 구매하려는 사람의 이야기로 예시를 들어보겠습니다.

금화를 1개 가지고 있는 사람A가 사과를 구매하려고 한다.

길을 가다 한 무인과일가게에 들어가서 보니
상자에 금화 100 개와 사과 101개가 들어있었다.

옆에 종이에는 이렇게 적혀있었다.

"상자에 남아있는 금화와 사과의 개수의 곱은 항상 10100 이어야합니다."

사람A 는 상자에 금화를 한개 넣고 사과를 하나 뺐다.

상자에 남은건 금화 101개와 사과 100개로 두 수의 곱은 10100으로 변함이 없다.

여기서 가장 핵심적이 되는 부분은 금화의 개수와 사과의 개수의 곱이 10100로 일정했다는 것입니다. 그렇다면 금화(x)와 사과(y)의 현재 개수를 알면 지불하는 금화(혹은 사과)의 양에 대해 수령하게 되는 사과(혹은 금화)의 양을 계산할 수 있다는 것입니다.

간단하게 수식으로 정리하면

reserve0(금화 개수) = r0
reserve1(사과 개수) = r1
k = r0 * r1
amount0In(지불하는 금액) = amt0In
amount1Out(수령하는 금액) = amt1Out

(r0 + amt0In)(r1 - amt1Out) = k

위 식을 다시 위의 사과예시에 대입해보면 다음과 같습니다.

k = r0(금화의 유동성=100) * r1(사과의 유동성=101) = 10100 (r0(금화의 유동성=100) + amt0In(A가 지불한 금화=1)) * (r1(사과의 유동성=101) - amt1Out(A가 받게 될 사과의 개수)) = k

Price Impact

CPMM 특성 상 같은 금액을 지불해도 유동성 풀 규모에 따라 받게되는 금액이 차이가 납니다.

50개의 token0 을 token1로 swap 하는 상황에서 예를 들어보겠습니다.

금화가 100개, 사과가 1000개 라고 했을 때
- 금화 : 사과 = 1 : 10
- 금화 50개에 대한 사과의 기대수량 = 500개
- 실제 스왑량
  - (100 + 50) * (1000 - 사과) = 100000
  - 사과 개수 ≈ 333.333
- PriceImpact = (1 - 실제수량 / 기대수량) * 100 ≈ 33.33%
금화가 10,000,000개, 사과가 100,000,000개 라고 했을 때
- 금화:사과 = 1: 10
  - 금화 50개에 대한 사과의 기대수량 : 500개
- 실제 스왑량
  - (10,000,000+50) * (100,000,000 - 사과) = 1,000,000,000,000,000
  - 사과 개수 ≈ 499.998
- PriceImpact = (1 - 실제수량 / 기대수량) * 100 ≈ 0.0004%

유동성이 클 수록 기대수량에 대한 오차가 작아집니다.

유동성 공급/제거와 수수료에 대한 내용은 다음편에서..

na_treeeum.log

홈 서버에 OpenClaw 개인비서 만들기 3편 --- OpenAI Embedding 429를 버리고 로컬 Memory Indexing 구성하기

1. 시작부터 429

2. 홈 서버에서 Embedding 모델이 돌아갈까?

3. llama.cpp Provider 설치

4. Provider를 local로 바꿨는데 또 안 된다

5. OpenClaw onboarding으로 Managed llama.cpp 구성

6. 첫 번째 삽질 --- libgomp.so.1이 없다

7. 두 번째 삽질 --- "Managed server prepared"인데 실패?

8. 실제로 파일은 다 받아졌는지 확인

9. 안 되면 코드를 까보자

10. OpenClaw이 만들려던 preset 확인

11. Managed llama.cpp 설정값까지 코드에서 찾기

12. 결국 Managed Provider 설정을 직접 넣었다

13. 기존 FTS-only Index를 다시 만들어야 한다

14. 박실장도 인덱싱

15. 그런데 llama-server가 바로 종료되는데?

16. 최종 구조

17. 이번 삽질 정리

18. 이번에 알게 된 것

Chat Model과 Embedding Model은 완전히 별개다

Semantic Search와 FTS는 다르다

Dirty: no를 확인하자

마무리

홈 서버에 개인비서 만들기 2편 - OpenClaw에 두 번째 직원 `박실장` 채용하기

1. 1편에서 만든 김비서부터 확인

2. 박실장 Calendar Agent 만들기

3. Discord Bot Token은 환경변수로 관리

4. 박실장은 일정관리실에서만 일하게 하기

5. 박실장 성격도 만들어주기

6. Google Calendar 연결하기

7. 첫 번째 대삽질 - OpenClaw 버전이 내려가버렸다

8. 기존 Dockerfile을 건드리지 말고 확장 image 만들기

9. 두 번째 대삽질 - /tmp 권한 때문에 Gateway 무한 재시작

10. Google OAuth Client 만들기

11. Docker 안에서는 호스트 경로가 안 보인다

12. Google OAuth 403 - Test user를 등록해야 한다

13. Google Calendar API를 안 켜면 또 403

14. 그런데 passphrase를 사람이 입력하면 AI 비서가 아니잖아?

15. 마지막 함정 - gog가 설치됐는데 박실장은 모른다

16. 최종 구조

17. 이번 삽질에서 배운 것

OpenClaw source Dockerfile을 함부로 다시 build하지 말자

Docker의 /tmp 권한도 중요하다

OAuth 성공과 API 사용 가능은 다른 문제다

Binary 설치와 Skill 노출도 다른 문제다

18. 이제 다음은?

홈 서버 구축기 - OpenClaw 개인 AI 비서 만들기 🦞

1. Docker부터 설치

2. 매번 sudo 붙이지 않게 docker group 추가

3. OpenClaw 설치

4. OpenClaw 초기 설정

5. Gateway 설정

6. OpenAI 연결

7. Discord를 OpenClaw의 메신저로 사용하기

8. "Gateway not detected"...?

9. Gateway Health Check

10. Discord Bot Token 등록

11. channels status --probe로 원인 찾기

12. Discord Message Content Intent

13. 이번엔 ECONNREFUSED?

14. 현재 구조

15. 자주 사용할 것 같은 명령어 정리

Container 상태 확인

Gateway 로그 확인

Gateway 재시작

Gateway Health Check

Discord 상태 확인

Channel 목록

Discord 추가

OpenClaw Doctor

마치며

EC2에 내 서버를 올리고 HTTPS로 서비스하기

1. 가장 먼저 HTTP가 무엇인가?

2. HTTP의 문제점

3. HTTPS란?

4. SSL과 TLS는 뭐가 다른가?

5. 그러면 SSL/TLS 인증서는 왜 필요한가?

7. Certbot은 뭐지?

8. 이제 Nginx는 왜 필요한가?

`Dirty: no`를 확인하자

11. `channels status --probe`로 원인 찾기