team-portal
by baryonlabs
README.md
# team-portal
**중소기업용 사내 링크 포탈.** 회사에서 쓰는 메일·ERP·NAS·SaaS 링크를 한 페이지에 모으고, 각 서비스가 살아 있는지 초록/빨강 점으로 보여줍니다. 카드는 웹 화면에서 바로 추가·삭제할 수 있고, **MCP 서버가 내장**되어 있어 Claude 같은 AI 에이전트에게 "회계 시스템 카드 추가해줘"라고 맡길 수도 있습니다.
[English README](README.en.md)

- **설치가 쉬움**: Node.js 20 이상만 있으면 됩니다. 외부 패키지 0개, 빌드 단계 없음.
- **설정은 파일 하나**: `portal.json` 하나에 회사 정보·섹션·카드·상태 점검이 모두 들어갑니다. 백업은 이 파일만 복사하면 됩니다.
- **상태 점검**: 서버가 15초마다 대신 확인하므로 `127.0.0.1`, `192.168.x.x` 같은 내부 주소도 점검됩니다.
- **네 가지 편집 방법**: 웹 편집 모드 · REST API · MCP(HTTP와 stdio) · CLI
- **포트 링크**: "이 서버의 8080 포트"처럼 등록하면 접속한 주소(IP, 사내 도메인, Tailscale 이름 등)에 맞춰 링크가 만들어집니다.
- **밝은/어두운 테마** 자동 전환, 모바일 화면 대응.
## 빠른 시작
```bash
git clone https://github.com/baryonlabs/team-portal.git
cd team-portal
cp examples/portal.example.json portal.json # 예시로 시작 (또는: node bin/team-portal.mjs init)
node bin/team-portal.mjs serve # http://127.0.0.1:8090
```
처음 실행하면 관리자 토큰을 만들어 화면에 한 번 보여주고 `portal.json.token` 파일에 저장합니다. 브라우저에서 `http://127.0.0.1:8090`을 열고 오른쪽 위 **✎ 편집**을 누른 뒤 이 토큰을 넣으면 카드를 추가·수정·삭제할 수 있습니다. 토큰을 직접 정하려면 `PORTAL_ADMIN_TOKEN` 환경변수를 쓰세요.
### 사내망에 공개하기
다른 직원 PC에서도 보려면 모든 네트워크 주소에서 접속을 받도록 실행합니다.
```bash
PORTAL_HOST=0.0.0.0 PORTAL_ADMIN_TOKEN=$(openssl rand -hex 16) node bin/team-portal.mjs serve
```
| 방법 | 명령 |
|---|---|
| macOS 상시 실행 (launchd) | `./deploy/install-macos.sh ~/.team-portal/portal.json 8090 0.0.0.0` (토큰을 만들어 출력합니다. 세 번째 값을 빼면 이 Mac에서만 접속됩니다) |
| Linux 상시 실행 (systemd) | `deploy/team-portal.service` 안의 안내를 따르세요 |
| Docker | `PORTAL_ADMIN_TOKEN=... docker compose up -d` (토큰을 비우면 `docker compose logs`에 생성된 토큰이 나옵니다. 데이터는 `portal-data` 볼륨) |
> 포탈 전체에 비밀번호를 걸려면 `PORTAL_BASIC_AUTH=아이디:비밀번호`를 설정하세요. `/healthz`만 예외입니다.
## 설정 (`portal.json`)
```json
{
"org": { "name": "한빛상사", "subtitle": "사내 도구를 한 곳에서", "logo": "🏢", "accent": "#4f8cff", "footer": "문의: 총무팀" },
"sections": [ { "id": "daily", "title": "매일 쓰는 도구", "hint": "전 직원" } ],
"cards": [
{ "id": "mail", "section": "daily", "title": "메일", "icon": "✉️", "url": "https://mail.google.com/", "badge": "Cloud" },
{ "id": "erp", "section": "daily", "title": "ERP", "icon": "📦", "port": 8069, "path": "/", "health": "http://127.0.0.1:8069/web/health" },
{ "id": "backup", "section": "daily", "title": "백업", "icon": "💾", "command": "sudo /opt/backup/run.sh" }
],
"checks": [ { "id": "db", "label": "DB 서버", "url": "http://10.0.0.5:8080/health" } ]
}
```
| 카드 필드 | 설명 |
|---|---|
| `id` | 영문 소문자·숫자·`-`. 비우면 제목으로 만듭니다 |
| `section` | 들어갈 섹션 id |
| `title`, `desc`, `icon`, `badge` | 화면에 보이는 이름, 설명, 이모지, 작은 라벨 |
| `url` | 전체 주소(`https://...`) 또는 포탈 자신의 경로(`/sites/`). `port`와 함께 쓸 수 없습니다 |
| `port`, `path` | 접속한 주소 기준의 포트와 경로 |
| `command` | 링크 없이 명령어만 보여주는 카드 |
| `health` | 서버가 확인할 주소. 응답 코드가 500 미만이면 정상. 자체 서명 인증서를 쓰는 https 주소(NAS 등)는 실패로 보이므로 http 주소를 쓰세요 |
| `order` | 섹션 안에서의 순서 (작을수록 앞) |
`checks`는 카드 없이 상단 상태 표시줄에만 나오는 점검 항목입니다(DB, 모델 서버, 인터넷 연결 등).
`fallbackProxy`(선택)에 주소를 넣으면, 포탈이 모르는 경로는 그 서버로 넘깁니다. 기존 사내 페이지 앞에 포탈을 붙일 때 기존 URL이 깨지지 않게 하는 용도입니다.
파일을 직접 고치거나 CLI로 바꾸면 서버가 다음 요청 때 자동으로 다시 읽습니다. 형식이 잘못된 동안에는 마지막 정상 설정을 계속 보여줍니다.
## MCP로 관리하기 (AI 에이전트)
포탈은 `/mcp` 경로에서 MCP(Model Context Protocol) 서버로도 동작합니다.
**Claude Code** — 실행 중인 포탈에 HTTP로 연결:
```bash
claude mcp add --transport http team-portal http://portal.example.local:8090/mcp \
--header "Authorization: Bearer <PORTAL_ADMIN_TOKEN>"
```
**Claude Desktop 등 stdio만 지원하는 클라이언트** — CLI가 중계합니다:
```json
{
"mcpServers": {
"team-portal": {
"command": "node",
"args": ["/path/to/team-portal/bin/team-portal.mjs", "mcp", "--url", "http://portal.example.local:8090"],
"env": { "PORTAL_TOKEN": "<PORTAL_ADMIN_TOKEN>" }
}
}
}
```
서버를 띄우지 않고 파일을 직접 편집하려면 `team-portal mcp --data ./portal.json`을 쓰면 됩니다.
| 도구 | 기능 |
|---|---|
| `list_portal` | 전체 설정 조회 |
| `get_status` | 상태 점검 결과 |
| `add_card` / `update_card` / `remove_card` | 카드 추가·수정·삭제 |
| `add_section` / `update_section` / `remove_section` | 섹션 관리 (카드가 남은 섹션은 `force` 필요) |
| `add_check` / `remove_check` | 상단 상태 점검 항목 관리 |
| `set_org` | 회사 이름·로고·색상 변경 |
읽기 도구는 누구나 쓸 수 있고, 변경 도구는 관리자 토큰이 있어야 합니다.
## REST API
| 메서드 | 경로 | 권한 |
|---|---|---|
| GET | `/api/portal`, `/api/status`, `/api/me`, `/healthz` | 공개 |
| POST | `/api/cards`, `/api/sections`, `/api/checks`, `/api/reload` | 관리자 |
| PATCH | `/api/cards/:id`, `/api/sections/:id`, `/api/org` | 관리자 |
| DELETE | `/api/cards/:id`, `/api/sections/:id?force=1`, `/api/checks/:id` | 관리자 |
```bash
curl -X POST http://127.0.0.1:8090/api/cards \
-H "Authorization: Bearer $PORTAL_ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"section":"daily","title":"그룹웨어","icon":"🏛️","url":"https://gw.example.com"}'
```
## CLI
```bash
node bin/team-portal.mjs list
node bin/team-portal.mjs add --id groupware --section daily --title "그룹웨어" --icon 🏛️ --url https://gw.example.com
node bin/team-portal.mjs remove groupware
```
`npm link`를 한 번 실행하면 어디서나 `team-portal` 명령으로 쓸 수 있습니다. 제목이 한글이면 `--id`로 영문 id를 정해 두는 것이 좋습니다(안 정하면 `card-x7k2p` 같은 id가 붙습니다).
## 보안
- **편집 권한**: 모든 변경은 관리자 토큰(`Authorization: Bearer ...`)이 있어야 합니다. 서버 컴퓨터에서 접속해도 마찬가지입니다. 토큰은 일정한 시간에 비교해, 응답 시간으로 토큰을 추측할 수 없습니다.
- **다른 사이트의 요청 차단**: 쓰기 요청은 `Content-Type: application/json`만 받습니다. 브라우저가 보낸 요청의 `Origin`이 포탈 주소와 다르면 거절합니다. 그래서 다른 사이트가 직원 브라우저를 이용해 몰래 보내는 요청(CSRF)과 DNS 리바인딩이 막힙니다. 다른 주소의 화면에서 API를 불러야 하면 `PORTAL_ALLOWED_ORIGINS`에 그 주소를 쉼표로 구분해 넣으세요.
- **기존 사이트로 넘기기(`fallbackProxy`)**: 넘길 때는 경로만 바꾸고 대상 서버는 고정합니다. 요청의 인증 정보와 쿠키는 지우고 보냅니다.
- **공개되는 정보**: 카드와 상태 점검의 주소(내부 주소 포함)는 포탈을 볼 수 있는 모든 사람에게 보입니다.
- **노출 범위**: 포탈은 링크 모음입니다. 인터넷에 직접 공개하기보다 사내망·VPN·Tailscale 안에서 쓰는 것을 권장합니다.
- **토큰 저장**: 웹 편집 모드의 토큰은 해당 브라우저 탭의 `sessionStorage`에만 저장됩니다.
## 개발
```bash
npm test # node:test, 외부 의존성 없음
```
MIT License · Baryon Labs
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues