접근 관리와 운영 화면
이 가이드를 마치면 누가 서버를 쓸 수 있는지 정하고, 운영 탭에서 모든 사용자의 맥 상태와 새 세션의 모델 목록을 관리할 수 있어요. 서버를 처음 올리는 절차는 서버 올리기를 보세요.
시작하기 전에
- 서버 올리기를 마쳐 서버가 돌고 있어야 해요.
- 운영자가 될 GitHub 계정 이름(
YOUR_LOGIN)이 서버의BRIDGE_ADMIN_LOGINS에 들어 있어야 해요.
운영자는 BRIDGE_ADMIN_LOGINS 에 든 GitHub 계정이에요. 쉼표로 여러 명을 둘 수 있어요. 운영자는 허용 목록에 없어도 로그인되고, 설정의 운영 탭을 봐요. 운영 탭은 SITE/admin 으로도 열려요. 운영자가 아닌 사람이 열면 "운영자만 볼 수 있어요" 가 보여요.
운영자가 볼 수 없는 것
운영 탭은 사람, 맥, 서버의 상태만 보여 줘요. 다른 사용자의 대화 내용은 보이지 않아요. 남의 맥 로그에 나오는 홈 경로 같은 값도 가려서 보여 줘요.
1. 운영자 정하기
서버의 환경 변수에 운영자를 넣고 컨테이너를 다시 띄우세요.
services:
bridge:
environment:
BRIDGE_ADMIN_LOGINS: YOUR_LOGIN,OTHER_LOGIN
GITHUB_ALLOWED_LOGINS: ""OTHER_LOGIN 은 두 번째 운영자의 GitHub 계정 이름이에요. 이름은 대소문자를 가리지 않아요. 환경 변수는 서버가 시작할 때 한 번만 읽으니, 바꾼 뒤에는 꼭 다시 띄우세요.
GITHUB_ALLOWED_LOGINS 는 처음부터 허용할 계정이에요. 비워 두고 2단계의 접근 관리에서만 허용해도 돼요. * 를 넣으면 GitHub 계정이 있는 누구나 들어와요.
2. 접근 관리에서 계정 허용하기
허용되지 않은 계정이 GitHub 로 로그인하면 그 사람에게는 "승인을 기다리는 중이에요" 가 보여요. 동시에 그 계정이 운영 탭의 접근 관리 에 "대기" 로 올라와요.
- 설정 → 운영 탭을 여세요.
- 접근 관리 목록에서 계정을 찾으세요. "대기" 계정이 맨 위에, 그 아래는 마지막 시도가 최근인 순서예요.
- 계정 줄의 버튼을 누르세요.
| 버튼 | 보이는 때 | 하는 일 |
|---|---|---|
| 허용 | 허용되지 않은 계정 | 로그인할 수 있게 해요 |
| 거부 | "대기" 계정 | 거부로 바꿔요. 확인 창에서 막기 를 눌러야 해요. 그 사람은 "허용되지 않은 계정입니다" 를 봐요 |
| 회수 | 허용된 계정 | 다시 막아요. 확인 창에서 막기 를 눌러야 해요 |
| 계정 허용 | 제목 줄 오른쪽 | GitHub 계정 이름을 넣어 미리 허용해요 |
허용된 사람은 다시 로그인하면 들어와요. 상태 배지는 "허용"(초록), "거부"(빨강), "대기"(주황)이고, 운영자에게는 "운영자" 배지가 붙어요. 줄 아래에는 마지막 시도 시각과 그 계정의 맥 수가 보여요.
회수하면 바로 끊겨요
회수하거나 거부하면 그 계정의 로그인이 모두 지워져요. 열려 있던 조작 페이지와 그 사람 맥의 연동도 그 자리에서 끊겨요. 그 뒤에 도착한 요청은 로그인이 필요하다는 답을 받아요.
서버 설정으로 허용된 계정
BRIDGE_ADMIN_LOGINS 나 GITHUB_ALLOWED_LOGINS 에 든 계정은 줄 아래에 "서버 설정으로 허용" 이 보이고, 버튼이 없어요. 이 계정의 접근은 화면에서 바꿀 수 없어요. 바꾸려면 환경 변수를 고치고 서버를 다시 띄우세요. API 로 바꾸려 해도 서버 설정으로 허용된 계정입니다. 설정(환경 변수)에서 바꿔야 합니다 가 돌아와요.
GITHUB_ALLOWED_LOGINS 에 * 가 있으면 제목이 "접근 관리 · 누구나 허용 중(*)" 으로 바뀌어요.
이름 놓아 주기
GitHub 계정 이름은 그 이름으로 처음 로그인한 GitHub 계정이 가져요. 이름을 바꾼 사람의 옛 이름을 다른 사람이 가져가도, 그 권한을 이어받지 못하게 하려는 거예요. 다른 GitHub 계정이 같은 이름으로 로그인하려 하면 줄에 "다른 계정이 쓰던 이름" 배지가 붙어요.
그 사람이 맞는 사람이라고 확인했을 때만 이름 놓아 주기 를 누르세요. 다음에 그 이름으로 로그인하는 계정이 허용·운영자 권한을 받아요. 지금 그 이름을 쓰는 계정은 곧바로 로그아웃되고 맥 연동도 끊겨요.
3. 서버와 맥 상태 보기
운영 탭 맨 위의 타일 5개가 서버를 요약해요.
| 타일 | 내용 |
|---|---|
| 서버 판 | 켜진 시간, 메모리. 문제가 있으면 BRIDGE_ORIGIN 없음, root 로 실행 중 |
| 최신 에이전트 build | 서버가 내주는 에이전트 build. 서명에 문제가 있으면 서명 안 됨, 업데이트 안 보냄 또는 서명 순번이 뒤로 감, 업데이트 안 보냄 |
| 연결된 맥 | 지금 연동된 맥 수 |
| 열린 조작 화면 | 지금 열린 조작 페이지 연결 수 |
| 세션 | 서버가 아는 세션 수(끝난 것 포함) |
아래의 사용자별 기기 는 사용자마다 그 사람의 맥을 보여 줘요.
- 맥 이름 옆 배지: "최신", "최신 아님", "업데이트 보류"(서버가 서명 문제로 업데이트를 보내지 않음).
- 키 배지: 맥의 에이전트 키와 연동 탭의 키가 맞는지("키 정상", "키 바꾸는 중", "키 확인" 등).
- 아랫줄: "연결됨" 또는 "끊김", build, 세션 수, 문제 문장.
맥 줄을 누르면 그 맥의 호스트 화면으로 가요. 호스트 화면에는 연결, 에이전트, 점검, 연동 탭, 세션별 싱크 상태와 호스트 로그가 있어요. 이 화면으로 문제를 찾는 방법은 문제 해결을 보세요.
같은 내용을 GET /api/admin/overview 로 받을 수 있어요. 응답의 pending 은 대기 중인 계정 수, server 는 위 타일의 값과 github·originSet·root·agentSigned·agentSeqBack, users 는 사용자별 맥 목록이에요. 운영자가 아니면 403 운영자만 볼 수 있습니다 예요. 자세한 내용은 주소와 HTTP API를 보세요.
4. 모델 목록 맞추기
새 세션 화면의 모델 목록은 맥의 Claude Code 가 아는 모델 목록과 맞춰요. 운영 탭의 모델 목록 에서 관리해요.
- 새 모델이 나오면 자동으로 갱신 스위치를 켜 두세요(기본은 켜짐). 켜 두면 6시간마다 연결된 맥 한 대에 모델 목록을 물어요. 운영자의 맥을 먼저 고르고, 없으면 연결된 아무 맥이에요.
- 바로 확인하려면 지금 확인 을 누르세요. 바뀌었으면 "목록을 바꿨어요 · 더함: …", 아니면 "바뀐 것이 없어요" 가 떠요.
- 상자 아래에서 마지막 확인 시각, 물어본 맥과 Claude Code 버전, 지난 변경(더함·뺌)을 확인하세요.
목록은 데이터 폴더의 models.json 에 남아요. 연결된 맥이 없으면 "연결된 맥이 없어 확인하지 못했어요" 가 보여요.
확인하기
- 운영자 계정으로 로그인했을 때 설정에 운영 탭이 보이면 성공이에요.
- 다른 GitHub 계정으로 로그인해 보세요. 그 계정이 접근 관리 에 "대기" 로 뜨고, 허용 을 누른 뒤 다시 로그인하면 들어가져요.
- 지금 확인 을 누른 뒤 "마지막 확인" 시각이 방금으로 바뀌면 모델 목록 동기화가 돼요.
문제가 생기면
- 운영 탭이 안 보여요: 로그인한 계정이
BRIDGE_ADMIN_LOGINS에 있는지, 바꾼 뒤 서버를 다시 띄웠는지 보세요. - 허용·회수 버튼이 없어요: 서버 설정으로 허용된 계정이에요. 환경 변수에서 바꾸세요.
- 서버 타일에
BRIDGE_ORIGIN 없음이 보여요: 서버 올리기의 4단계를 따라BRIDGE_ORIGIN을 정하세요. - "서명 안 됨, 업데이트 안 보냄" 이 보여요: 에이전트 서명 키를 보세요.