For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/admin.md (or send Accept: text/markdown).

관리자 콘솔

플랫폼 검사, 공지, 피처 플래그.

이 가이드에 대해 질문하기

초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고, 웹 로컬 설정을 완료하고, 편집기의 루트에서 이 모노레포를 엽니다. 웹 설정은 apps/web/.env.local에 속합니다. Next.js는 루트 .env를 읽지 않습니다. 기본 가짜 모드의 /dashboard는 데이터베이스가 없는 데모입니다. /auth에는 마이그레이션된 데이터베이스가 필요합니다.

빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.

1. 로컬 테스트 계정을 만들기 전에 서버 전용 ADMIN_EMAILS 목록에 자신의 주소를 추가하고 앱을 다시 시작하세요.

2. 마이그레이션된 테스트 데이터베이스에 가입하고 /admin를 엽니다. 사용 가능한 사용자 및 조직 페이지를 검사합니다.

3. 이는 작업 공간 소유권이 아닌 플랫폼 관리자를 부여합니다. 액세스가 거부되면 정확한 이메일과 서버 구성을 확인하세요. 임의의 사용자를 승격시키거나 프로덕션에 대해 테스트하지 마십시오.

사용자 정의 코드의 경우 제공된 prompts/README.md로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 prompts/new-app-screen.md, 공개 페이지의 경우 prompts/new-landing-page.md)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 AGENTS.md, .ai/PROJECT_CONTEXT.md 및 일치하는 .ai/ 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

관리 경계 만들기

ADMIN_EMAILS는 쉼표로 구분된 서버 전용 부트스트랩 목록입니다. 등록된 사용자는 가입 시 플랫폼 관리자 역할을 받습니다. 이것이 없으면 승인된 데이터베이스/관리자 경로를 통해 액세스 권한을 부여하십시오. 첫 번째 임의 방문자를 관리자로 만들지 마십시오.

플랫폼 관리자는 워크스페이스 소유자/관리자와 다릅니다. /admin와 해당 사용자, 조직, 플래그, 공지사항 및 대기자 명단 페이지는 플랫폼 역할을 확인합니다.

구현된 컨트롤 사용

기본 Better Auth 엔진은 관리자 사용자 관리, 금지 및 가장 기능을 제공합니다. 앱은 감사 추적을 통해 플랫폼 보기를 구성합니다. 확인된 관리자 액세스로 가장을 제한하고 상태를 표시하며 종료 시 원래 관리자 세션을 복원합니다.

Auth.js는 Better Auth 관리 플러그인을 자동으로 상속하지 않습니다. 엔진을 전환하기 전에 admin.ts, admin-actions.ts 및 인증 제공자 동작을 검토하세요.

권한 있는 작업 확인

비관리자 거부, 관리자 액세스, 금지된 사용자 세션, 가장 시작/중지 및 활성화한 작업을 테스트합니다. 모든 관리 경로를 공개 색인 외부에 유지하세요.

설치 및 설정

/admin 표면은 워크스페이스, 멤버, 프로덕트 상태에 대한 운영자 검사 뷰입니다. ADMIN_EMAILS(또는 소비 프로덕트의 admin 플러그인 설정)가 누가 접근하는지 결정하고, 각 admin 라우트는 서버에서 인가를 다시 확인합니다.

피처 플래그(feature-flag-runtime.ts)는 구성되지 않은 모든 것을 기본으로 비활성화합니다 — 누락된 플래그가 표면을 조용히 활성화할 수 없습니다. 플래그별 오버라이드는 featureFlagOverride 테이블에 있습니다.

/admin                    operator dashboard
announcement-actions.ts   broadcast in-app notices
resolveFeatureFlags(...)  bulk flag resolution for a caller context

구현 워크플로

admin 액션은 검사와 지원 작업(워크스페이스 조회, 멤버 관리, 공지 브로드캐스트)에 사용합니다. 뮤테이션은 감사되고 인가는 내비가 아닌 액션 경계에서 확인되게 유지하세요.

기능은 플래그 뒤로 롤아웃합니다: 코드를 다크로 출시하고, 워크스페이스별 또는 전역으로 활성화하고, 표면이 영구적이 되면 플래그를 제거합니다. 플랫폼 임퍼서네이션은 프로덕트의 PRODUCT.md가 명시적으로 허용하지 않는 한 동결 상태입니다.

검증 및 문제 해결

비관리자가 거부되는지, 비활성 플래그가 표면을 엔드 투 엔드로 숨기는지(내비, 라우트, 액션), 오버라이드가 대상에만 해석되는지, 공지가 의도된 청중에게 도달하는지 확인합니다. admin 테스트는 거부 경로를 먼저 커버해야 합니다.