124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
# wikijs
|
|
|
|
[Wiki.js](https://js.wiki/) Podman Quadlet 구성.
|
|
`postgres-main` 공유 인스턴스를 DB로 사용하고, `proxy.network`에 배치된다.
|
|
|
|
## 서비스 정보
|
|
|
|
| 항목 | 값 |
|
|
|---|---|
|
|
| 이미지 | `ghcr.io/requarks/wiki:2` |
|
|
| 내부 주소 | `10.89.0.45:3000` |
|
|
| 도메인 | `wiki.du5t.xyz` |
|
|
| DB | `postgres-main` — `wikijs` 데이터베이스 |
|
|
| 데이터 | `/podman/data/wikijs/data` |
|
|
| 인증 | Authentik OAuth2 (strategy: `oauth2`, Provider PK=9) |
|
|
|
|
## 파일 구성
|
|
|
|
```
|
|
wikijs.container ← Quadlet 컨테이너 정의
|
|
wikijs.env.example ← 환경변수 템플릿
|
|
```
|
|
|
|
실제 환경변수 파일은 `/podman/env/wikijs.env` (서버 로컬, 미추적).
|
|
|
|
## Authentik 연동 상세
|
|
|
|
### Provider 정보
|
|
|
|
| 항목 | 값 |
|
|
|---|---|
|
|
| Provider PK | `9` |
|
|
| Provider명 | `wikijs-provider` |
|
|
| Strategy | `oauth2` (passport-oauth2, Generic OAuth2) |
|
|
| Strategy UUID | `a2d864cd-dfc4-4a75-a891-d768fd8d173a` |
|
|
| Callback URL | `https://wiki.du5t.xyz/login/a2d864cd-dfc4-4a75-a891-d768fd8d173a/callback` |
|
|
| Authorization Flow | implicit-consent |
|
|
|
|
> **`oidc` 대신 `oauth2` 전략을 사용하는 이유**
|
|
> Wiki.js에 포함된 `passport-openidconnect` v0.1.2가 Authentik의 토큰 응답을 처리하는 과정에서
|
|
> `invalid_grant` 오류를 반환한다. `passport-oauth2`는 JWT ID 토큰 검증 없이 userinfo 엔드포인트만
|
|
> 사용하므로 이 문제를 우회한다.
|
|
|
|
### Authentik Property Mappings (필수)
|
|
|
|
Provider PK=9에 아래 3개 매핑이 없으면 userinfo 엔드포인트가 `Scope mismatch` 오류를 반환한다.
|
|
|
|
| Mapping | Scope |
|
|
|---|---|
|
|
| `authentik default OAuth Mapping: OpenID 'openid'` | openid |
|
|
| `authentik default OAuth Mapping: OpenID 'profile'` | profile |
|
|
| `authentik default OAuth Mapping: OpenID 'email'` | email |
|
|
|
|
```bash
|
|
AUTHENTIK_TOKEN="<token>"
|
|
curl -s -H "Authorization: Bearer $AUTHENTIK_TOKEN" \
|
|
"https://auth.du5t.xyz/api/v3/providers/oauth2/9/" | python3 -c \
|
|
"import sys,json; print(json.load(sys.stdin)['property_mappings'])"
|
|
```
|
|
|
|
### Wiki.js 전략 등록 (GraphQL)
|
|
|
|
config 값은 반드시 `{"v": <value>}` 형태로 JSON 인코딩해야 한다.
|
|
|
|
```bash
|
|
WIKI_TOKEN=$(curl -s -X POST https://wiki.du5t.xyz/graphql \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"query":"mutation{authentication{login(username:\"<email>\",password:\"<pass>\",strategy:\"local\"){jwt}}}"}' \
|
|
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['authentication']['login']['jwt'])")
|
|
```
|
|
|
|
전략 등록 시 주요 config 항목:
|
|
|
|
| key | value |
|
|
|---|---|
|
|
| `authorizationURL` | `https://auth.du5t.xyz/application/o/authorize/` |
|
|
| `tokenURL` | `https://auth.du5t.xyz/application/o/token/` |
|
|
| `userInfoURL` | `https://auth.du5t.xyz/application/o/userinfo/` |
|
|
| `userIdClaim` | `sub` |
|
|
| `displayNameClaim` | `name` |
|
|
| `emailClaim` | `email` |
|
|
| `scope` | `openid profile email` |
|
|
| `enableCSRFProtection` | `false` |
|
|
|
|
## 그룹 및 권한 구조
|
|
|
|
| 그룹 ID | 이름 | autoEnrollGroups | 비고 |
|
|
|---|---|---|---|
|
|
| 1 | Administrators | — | `manage:system` 권한, 관리자 페이지 접근 |
|
|
| 2 | Guests | — | 읽기 전용 |
|
|
| 3 | Users | ✓ (SSO 신규 유저 자동 배정) | 읽기/쓰기 |
|
|
|
|
> **pageRules `path` 주의사항**
|
|
> 그룹 pageRules의 `path` 값은 `""` (빈 문자열)이어야 한다.
|
|
> `"/"` 로 설정 시 checkAccess 내부에서 `"/" + path = "//"` 가 되어 모든 경로 매칭이 실패한다.
|
|
|
|
관리자 계정은 별도로 Administrators 그룹에 추가:
|
|
|
|
```sql
|
|
-- Wiki.js PostgreSQL (postgres-main, wikijs DB)
|
|
INSERT INTO "userGroups" ("userId", "groupId") VALUES (<userId>, 1);
|
|
```
|
|
|
|
## 초기 설정 순서
|
|
|
|
1. `systemctl start wikijs`
|
|
2. Setup Wizard 완료 (`POST /finalize` — 관리자 이메일/비밀번호 설정)
|
|
3. Authentik: Provider(PK=9) + Application 생성, property_mappings 3개 설정
|
|
4. Wiki.js GraphQL: `updateStrategies` mutation으로 `oauth2` 전략 등록
|
|
5. 관리자 계정을 Administrators 그룹(id=1)에 추가
|
|
|
|
## 운영
|
|
|
|
```bash
|
|
# 상태 확인
|
|
systemctl status wikijs
|
|
|
|
# 로그
|
|
podman logs --tail 50 wikijs
|
|
|
|
# 재시작
|
|
systemctl restart wikijs
|
|
```
|