Athena

당신의 AI가 기록하는 개인 위키이며, 당신도 직접 탐색할 수 있습니다.

Athena는 Wiki.js 앞에 MCP 서버를 둡니다. 당신의 어시스턴트가 위키를 검색하고, 페이지를 읽고, 새로운 페이지(메모, 문서, 전체 대화)를 기록합니다. AI가 작성하는 모든 것은 평범한 Markdown 페이지로, 특정 모델이 사라진 후에도 오래도록 열고, 편집하고, 보관할 수 있습니다.

Claude / ChatGPT / Cursor
        │  MCP over HTTPS
        ▼
   athena-mcp ──── search ──▶ Wiki.js (keyword) + Postgres (meaning)
        │          read ────▶ Wiki.js
        └────────  write ───▶ Wiki.js ──▶ athena-indexer ──▶ Postgres

Wiki.js가 진실을 보유합니다. 벡터 인덱스는 검색을 돕기 위한 것일 뿐이며, 언제든지 삭제하고 다시 구축할 수 있습니다.

퀵스타트

로컬에서 약 5분 안에 시작합니다. 인터넷에서 접근하려면 서버에 배포하기를 먼저 읽어보세요.

git clone https://github.com/jannismilz/athena.git
cd athena
cp .env.example .env
$EDITOR .env          # fill in every CHANGE_ME, one per secret:
                      #   openssl rand -hex 32
docker compose up -d

그런 다음:

1. Wiki.js를 열고 설정 마법사를 완료합니다.

2. Wiki.js에서: Administration → API로 이동하여 활성화하고 토큰을 생성한 후 .env 파일에 WIKI_API_TOKEN으로 입력합니다.

3. docker compose up -d를 다시 실행하여 적용합니다.

4. 대시보드를 열고 DASHBOARD_TOKEN으로 로그인합니다.

데이터는 체크아웃 내부가 아닌 옆에 있는 data/ 디렉토리에 기록되므로, 어떤 git 작업으로도 삭제할 수 없습니다. 다른 위치를 원한다면 ATHENA_DATA_DIR을 변경하세요.

포트를 공개하지 않으므로, 리버스 프록시를 통해 서비스에 접근하거나 테스트 시 임시로 ports: 매핑을 추가하세요.

첫 번째 시작 시 수백 MB 크기의 임베딩 모델을 다운로드합니다. 인덱서는 준비될 때까지 재시도하므로, 첫 부팅 시 1-2분 동안 embeddings가 비정상으로 보이는 것은 정상입니다.

Related MCP server: wiki-js-mcp

AI 연결하기

모든 서비스는 MCP_PUBLIC_URL에서 제공되며, 이 URL은 경로 없이 https://로 시작하는 순수한 오리진이어야 합니다. /mcp가 아니어야 합니다.

Claude.ai → 설정 → 커넥터 → 사용자 정의 커넥터 추가

• URL: https://athena-mcp.example.com/mcp

• 클라이언트 ID와 시크릿은 비워둡니다. Athena가 직접 클라이언트를 등록합니다.

• 브라우저 페이지에서 비밀번호를 요청합니다. 이 비밀번호는 MCP_TOKEN입니다.

Cursor, Claude Desktop 및 기타 헤더 클라이언트

{
  "mcpServers": {
    "athena": {
      "url": "https://athena-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_TOKEN" }
    }
  }
}

도구

append_to_page는 알아둘 가치가 있는 도구입니다: 사실을 추가할 때 전체 페이지를 다시 작성하지 않고 단락 하나만 추가하면 됩니다.

검색이 잘 되는 이유. 정확한 용어는 Wiki.js 전체 텍스트 인덱스를, 모호한 질문은 벡터 인덱스를 사용하며, 결과는 상호 순위 융합으로 결합되어 어떤 출처도 다른 출처를 묻히지 못합니다. 청크는 자신 위의 제목을 기록하므로 반환되는 결과는 맥락을 유지합니다. 어시스턴트가 접근하는 모든 페이지는 어떤 어시스턴트가 언제 접근했는지 기록되며, 이는 모델이 스스로 주장하는 내용이 아닌 인증된 클라이언트에서 가져옵니다.

대시보드

8082 포트에서 실행되는 자체 서비스입니다. DASHBOARD_TOKEN으로 로그인하며, URL에 토큰이 포함되지 않습니다. 스크립트의 경우 Bearer 헤더를 사용하세요:

curl -H "Authorization: Bearer $DASHBOARD_TOKEN" \
  https://wiki.example.com/dashboard/api/metrics?days=30

세 번째 행이 가장 가치 있습니다. 모든 항목은 작성할 가치가 있는 페이지입니다.

대시보드는 두 가지 측면에서 읽기 전용입니다: 데이터를 쓰지 않으며, Postgres에 athena_readonly 역할로 연결됩니다. 이 역할은 SELECT 권한만 가집니다. 수치는 Postgres에서 집계되어 캐시되므로 새로고침 비용이 거의 없습니다.

서버에 배포하기

4GB VPS로 CPU에서 임베딩 모델을 포함한 모든 것을 실행할 수 있습니다.

1. 호스트 및 방화벽

sudo ufw default deny incoming && sudo ufw default allow outgoing
sudo ufw allow 22/tcp && sudo ufw allow 80/tcp && sudo ufw allow 443/tcp
sudo ufw enable

Docker를 설치한 후, 배포를 소유할 사용자를 생성합니다:

sudo useradd --create-home --shell /bin/bash athena
sudo usermod -aG docker athena

해당 사용자로 compose를 실행하고, 절대 sudo를 사용하지 마세요. 그렇지 않으면 바인드 마운트가 root 소유가 됩니다. docker 그룹에 속하는 것은 호스트에서 root와 동일하므로, 그룹을 소규모로 유지하세요.

2. DNS

호스트를 가리키는 두 개의 A 레코드:

3. 디렉토리 구성 및 설정

Athena가 기록하는 모든 것은 ATHENA_DATA_DIR 하나의 설정을 따르므로, 전체 설치를 단일 디렉토리 아래에 배치할 수 있습니다. 수명 주기가 다른 두 개의 하위 디렉토리를 사용하세요:

/athena
├── app/     the git repository   replaceable, thrown away on every upgrade
└── data/    postgres, state,     irreplaceable, never touched by git
             uploads, backups

이들은 중첩되지 않은 형제 디렉토리이며, 이것이 핵심입니다. data/는 .gitignore에 있으며, git clean -xdf는 무시된 파일을 삭제하므로 체크아웃 내부의 데이터는 확인이나 취소 없이 한 번의 명령으로 삭제될 수 있습니다. 형제 디렉토리는 git 작업으로 접근할 수 없습니다.

기본 ATHENA_DATA_DIR=../data는 이 레이아웃을 자동으로 제공하므로, 기억할 것이 없습니다.

sudo mkdir -p /athena && sudo chown athena:athena /athena
cd /athena
git clone https://github.com/jannismilz/athena.git app
cd app
cp .env.example .env
chmod 600 .env        # it holds every secret

ATHENA_DATA_DIR의 기본값은 ../data이며, 이는 compose 파일이 있는 디렉토리를 기준으로 확인됩니다. 위와 같이 /athena/app에 클론하면 데이터는 설정할 것 없이 /athena/data에 저장됩니다. 시크릿을 설정하세요:

POSTGRES_PASSWORD=...
MCP_TOKEN=...
DASHBOARD_TOKEN=...
DASHBOARD_DB_PASSWORD=...
MCP_PUBLIC_URL=https://athena-mcp.example.com
WIKI_PUBLIC_URL=https://wiki.example.com

Compose는 첫 번째 시작 시 /athena/data와 그 하위 디렉토리를 생성합니다. 모든 docker compose 명령은 /athena/app에서 실행하세요.

/athena/data
├── postgres/     the wiki, users, settings, uploads, activity log, vectors
├── wikijs/       Wiki.js config, cache, upload cache
├── mcp/          oauth-state.json, the tokens issued to AI clients
├── indexer/      index bookkeeping, rebuilt automatically if lost
├── embeddings/   the downloaded model
└── backups/      local dumps plus status.json

postgres/만이 대체 불가능하며, 백업 컨테이너가 매시간 덤프합니다. 나머지는 자동으로 재생성되거나 재연결 한 번으로 해결됩니다.

파일 시스템 계층 규칙을 따르려면 데이터를 /srv/athena에, 체크아웃을 /opt/athena에 배치하세요. 단일 루트 레이아웃은 하나의 작업만 수행하는 머신에서 더 간단하며, 둘 다 작동합니다. ATHENA_DATA_DIR만 결정하면 됩니다.

4. 리버스 프록시

컨테이너는 포트를 공개하지 않습니다. 서비스는 두 개의 네트워크에 있습니다:

• athena, 내부 네트워크. Postgres, 임베딩 모델 및 인덱서만 여기에 있으므로, 손상된 프록시가 데이터베이스에 접근할 수 없습니다.

• athena-edge, 리버스 프록시가 연결되는 네트워크. 아래 세 서비스만 이 네트워크에 있습니다.

다음과 같이 라우팅하세요:

X-Forwarded-For를 전달하세요: 로그인은 IP당 속도를 제한하며, 이 헤더가 없으면 모든 시도가 프록시에서 온 것으로 보입니다.

nginx를 아래와 같이 athena-edge 네트워크에 연결된 컨테이너로 실행하거나, 127.0.0.1에 바인딩된 ports: 매핑으로 호스트에서 실행하세요. 에지 네트워크에 연결하면 프록시가 Wiki.js, MCP 서버 및 대시보드에만 접근할 수 있고 나머지는 접근할 수 없습니다.

server {
    listen 80;
    server_name wiki.example.com;

    location / {
        proxy_pass http://wikijs:3000;
        proxy_http_version 1.1;
        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;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        client_max_body_size 100M;
        proxy_read_timeout 120s;
    }

    location /dashboard/ {
        proxy_pass http://dashboard:8082/;
        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;
    }
}

server {
    listen 80;
    server_name athena-mcp.example.com;

    location / {
        proxy_pass http://mcp:8080;
        proxy_http_version 1.1;
        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;

        # MCP streams responses. Without these, long tool calls appear to hang.
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

그런 다음 certbot으로 인증서를 발급하거나, 이미 TLS를 종료하는 곳에서 처리하세요.

여기에는 플랫폼 특화된 내용이 없습니다. Compose를 실행하고 자체 프록시를 제공하는 PaaS는 모두 .env 파일에 세 가지 설정이 필요합니다:

ATHENA_DATA_DIR=../files          # Dokploy's persistent directory
ATHENA_EDGE_NETWORK=dokploy-network
ATHENA_EDGE_EXTERNAL=true

ATHENA_DATA_DIR이 가장 중요합니다: Dokploy는 재배포 시 절대 바인드 마운트 경로를 정리하므로, 절대 경로를 사용하면 데이터베이스가 파괴됩니다. 앱 디렉토리에 상대적인 경로는 유지됩니다.

그런 다음 플랫폼 UI에서 서비스와 포트를 가리키는 도메인을 추가하세요:

플랫폼이 자체 라우팅 레이블을 생성하고 TLS를 처리하므로, nginx 섹션은 완전히 건너뛰세요. compose 파일을 포함한 다른 모든 것은 변경되지 않습니다.

이미지를 레지스트리에 게시할 필요는 없습니다: Dokploy는 저장소에서 빌드합니다. 네 개의 이미지를 빌드하는 것은 Postgres 및 임베딩 모델과 메모리를 경합하므로, 작은 호스트에서는 CI에서 빌드하고 pull하는 것이 좋습니다.

5. 시작한 후 위키 잠그기

docker compose up -d && docker compose ps

Wiki.js 마법사를 즉시 완료하세요. 완료하기 전까지 호스트를 찾은 사람이 관리자 계정을 생성할 수 있습니다. 그런 다음 Wiki.js에서:

• Groups → Guests: 위키를 공개하지 않을 경우 읽기 권한을 제거하세요.

• Auth: 자체 등록을 비활성화하세요.

• API: 활성화하고 WIKI_API_TOKEN용 토큰을 생성하세요.

6. 확인

curl -s https://athena-mcp.example.com/health

# Must reject unauthenticated calls:
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://athena-mcp.example.com/mcp
# expected: 401

백업

하나의 pg_dump가 완전한 백업입니다. Wiki.js는 페이지, 기록, 사용자, 권한, 설정 및 모든 업로드 파일의 바이트를 Postgres에 저장합니다. 업로드는 assetData 테이블에 저장되며, data/wikijs/uploads 아래의 파일은 캐시일 뿐입니다. Athena의 활동 로그와 검색 벡터는 동일한 서버의 두 번째 데이터베이스에 있습니다.

backup 컨테이너는 매시간 실행됩니다. 각 실행은 두 데이터베이스를 덤프하고, 모든 덤프가 읽을 수 있는지 확인하며, 로컬 사본을 유지하고, rclone 대상으로 푸시하며, 업로드가 일치하는지 확인한 후에만 정리합니다. 실패한 실행이 마지막 좋은 백업을 삭제할 수 없습니다.

docker compose run --rm backup now            # take one now
docker compose run --rm backup restore list   # see what exists
docker compose logs -f backup                 # watch the schedule

.env에서 전체를 구성하세요. S3, Backblaze, Wasabi, MinIO, Hetzner 등 모든 rclone 대상이 작동합니다. BACKUP_REMOTE를 비워두면 백업이 호스트에만 유지됩니다.

crypt 원격을 추가하고 BACKUP_REMOTE를 가리키세요. 그러면 대상은 파일 이름을 포함하여 암호문만 수신합니다.

BACKUP_REMOTE=crypt:
RCLONE_CONFIG_CRYPT_TYPE=crypt
RCLONE_CONFIG_CRYPT_REMOTE=s3:my-bucket/athena
RCLONE_CONFIG_CRYPT_PASSWORD=<rclone obscure ...>
RCLONE_CONFIG_CRYPT_PASSWORD2=<rclone obscure ...>

두 비밀번호를 모두 비밀번호 관리자에 보관하세요. 비밀번호가 없으면 본인을 포함한 누구도 백업을 읽을 수 없습니다.

복원

필요하기 전에 이 과정을 연습하세요. 아무도 실행하지 않은 복원은 추측에 불과합니다.

docker compose run --rm backup restore list
docker compose stop wikijs mcp indexer dashboard
docker compose run --rm backup restore run 2026-08-18T115529Z
docker compose start wikijs mcp indexer dashboard

복원을 확인하기 위해 데이터베이스 이름을 입력하라고 요청합니다. restore fetch <stamp>는 백업을 복원하지 않고 다운로드하며, 각 덤프가 읽을 수 있는지 보고합니다.

검색 색인은 이후 자동으로 복구됩니다. 색인기가 모든 페이지를 다시 읽고 내용이 변경된 항목을 다시 임베딩합니다.

구성

모든 것은 환경 변수에서 가져옵니다. 각 서비스는 부팅 시 자체 구성을 검증하고 잘못된 항목 목록과 함께 종료되므로, 오타가 새벽 3시가 아닌 즉시 실패합니다.

다섯 가지 비밀은 모두 사용자가 생성합니다. Claude, OpenAI 또는 다른 사람의 자격 증명이 .env에 저장되는 일은 없습니다.

실행되는 서비스

별도의 벡터 데이터베이스는 없습니다. 벡터는 Postgres에 저장되므로 하나의 백업으로 모든 것을 포괄합니다.

ARM 호스트에서 임베딩 이미지는 linux/amd64 전용으로 게시되며 네이티브로 실행되지 않습니다. EMBEDDINGS_PROVIDER=openai를 Ollama와 같은 OpenAI 호환 엔드포인트로 설정하세요.

EMBEDDINGS_MODEL을 변경하면 벡터 너비가 변경되며, 두 모델의 벡터는 비교할 수 없으므로 인덱서가 테이블을 다시 빌드하고 모든 페이지를 다시 임베딩합니다. Wiki.js 콘텐츠는 변경되지 않습니다.

보안

각 컨테이너는 자신이 사용하는 자격 증명만 받습니다. 대시보드는 POSTGRES_PASSWORD도 WIKI_API_TOKEN도 받지 않으므로, 대시보드가 손상되어도 읽기 권한만 얻을 뿐 그 이상은 아닙니다. 언제든지 확인할 수 있습니다:

docker compose exec dashboard env | grep -iE 'PASSWORD|TOKEN'

• 인증되지 않은 MCP 요청은 401을 반환하며 설명이 없습니다.

• 두 로그인 경로 모두 주소당 5회 실패 후 제한됩니다. 로그인 링크는 3회 시도 후 소진됩니다.

• 대시보드 세션은 만료 시간과 nonce를 포함한 서명된 쿠키이며, 토큰 자체는 아닙니다. HttpOnly, SameSite=Strict, 교차 사이트 POST는 거부됩니다.

• 비밀 비교는 일정 시간 내에 수행됩니다.

• 프록시 헤더는 루프백에서만 신뢰하므로 원격 클라이언트가 주소를 위조하여 제한을 회피할 수 없습니다.

• 컨테이너는 루트가 아닌 사용자로 실행됩니다.

의도적으로 생략됨: 도구별 권한. 인증된 모든 클라이언트는 delete_page를 포함한 모든 도구를 호출할 수 있습니다. Wiki.js는 페이지 기록을 유지하므로 삭제는 복구 가능하지만, MCP_TOKEN을 위키에 대한 전체 쓰기 권한으로 취급하세요. 또한 Athena는 단일 소유자를 가정합니다. Wiki.js에는 위키를 읽기 위한 자체 사용자가 있습니다.

MCP_TOKEN은 두 가지 방식으로 작동합니다. AI 클라이언트가 두 가지 방식으로 인증하기 때문입니다.

헤더 클라이언트(Cursor, Claude Desktop 등)는 Authorization: Bearer <MCP_TOKEN>을 보냅니다. 이것이 전체 메커니즘입니다.

브라우저의 Claude.ai는 그렇게 할 수 없습니다. 해당 커스텀 커넥터는 OAuth만 지원하며, MCP 사양은 동적 클라이언트 등록을 요구하므로 브라우저 Claude를 수락하는 서버는 인증 서버여야 합니다. Athena는 다음을 구현합니다:

1. Claude가 자신을 등록하고 생성된 클라이언트 ID를 받습니다. 사용자의 비밀은 관여되지 않습니다.

2. Claude가 사용자를 자체 서버의 로그인 페이지로 보냅니다.

3. 사용자가 비밀번호로 MCP_TOKEN을 입력합니다. 이것이 인간 승인 단계입니다.

4. Athena가 자체적으로 만든 Claude 토큰을 발급합니다.

이 토큰은 data/mcp/oauth-state.json에 기록되며, 절대 .env에 기록되지 않습니다. 다음으로 취소할 수 있습니다:

rm data/mcp/oauth-state.json && docker compose restart mcp

브라우저 Claude를 사용하지 않는다면, 이 모든 것을 무시하세요. Bearer 경로는 이와 관련이 없습니다.

운영

docker compose logs -f mcp
curl -s localhost:8081/stats | python3 -m json.tool

# Force a full reconciliation
docker compose exec -T indexer bun -e 'await fetch("http://127.0.0.1:8081/sync",{method:"POST"})'

업그레이드. 항상 먼저 백업하세요. Wiki.js는 시작 시 자체 마이그레이션을 실행하며, 컨테이너를 중지해도 되돌릴 수 없습니다.

docker compose run --rm backup now
git pull && docker compose build && docker compose up -d

Postgres는 다른 주 버전에서 작성된 데이터 디렉터리를 읽을 수 없습니다. 덤프, 삭제, 복원 순서로 진행:

docker compose run --rm backup now             # on the OLD version
docker compose down
mv data/postgres data/postgres.old             # keep until you are happy
# edit the image tag in docker-compose.yml and the FROM line in
# docker/backup/Dockerfile to the same new major version
docker compose build backup
docker compose up -d postgres
docker compose run --rm backup restore run <stamp>   # once per database
docker compose up -d

벡터 인덱스는 다른 모든 것과 함께 복원되므로, 다시 임베딩할 필요가 없습니다.

개발

bun install
bun test          # 145 tests
bun run check     # typecheck, lint, test

Bun은 TypeScript를 직접 실행하므로 빌드 단계가 없으며 컨테이너가 소스를 실행합니다. bun run --cwd packages/dashboard preview는 샘플 데이터가 포함된 preview.html을 생성합니다.

구성 요소 간 관계:

• 인덱서는 증분 방식입니다. 각 페이지의 지문을 기록하고 변경되지 않은 항목은 건너뛰므로, 변경되지 않은 위키를 한 번 스캔하는 데 비용이 들지 않습니다.

• 관리자 자격 증명이 있는 모든 서비스는 부팅 시, 조언 잠금 아래에서 데이터베이스를 준비하므로 시작 순서는 중요하지 않습니다.

• 대시보드는 인라인 SVG 차트가 포함된 서버 렌더링 HTML입니다. 클라이언트 JavaScript, 차트 라이브러리, 빌드 단계가 없습니다.

웹사이트 게시. website/index.html은 터치할 때마다 GitHub Pages에 배포됩니다. 먼저 수동으로 Pages를 한 번 활성화하세요: Settings → Pages → Build and deployment → Source: GitHub Actions. 이는 자동화할 수 없습니다. Pages 사이트 생성에는 관리 권한이 있는 토큰이 필요하며 GITHUB_TOKEN에는 그 권한이 없기 때문입니다.

라이선스

Apache-2.0. LICENSE를 참조하세요.