jointrashposs/content/ko/docs/3.for-admin/install/resources/troubleshooting.md

수동 설치 시 문제 해결

2018년 10월 07일 / 2021년 12월 20일 최종 업데이트 / 문책 aqz/tamaina

MisskeyInstallBattle 참가자가 늘어났지만, 그에 따라 시간이 지날수록 중경상자가 증가하고 있습니다.
이 글에서는 이러한 부상을 줄이기 위해 과거에 사고가 발생했던 부분의 경향과 대책을 알기 쉽게 설명합니다.

먼저, 구축 안내서를 숙지하시기 바랍니다.

또한, 제 저서 Ubuntu용 systemd 해설, Oracle Cloud 버전 상세 해설도 참고해 주시면 감사하겠습니다.

우분투용 쉘 스크립트 안내

우분투에 대한 설명은 복사, 붙여넣기로만 이루어져 있어 재미없어요!시간이 걸린다!어쨌든 귀찮다!

……어라, 복사-붙여넣기만으로 할 수 있다면 완전 자동화가 가능하지 않을까?

그래서 쉘 스크립트로 거의 모든 것을 해주는 것을 만들어 보았습니다!
[**자세한 내용 및 사용법은 여기에서 확인하세요!]**https://github.com/joinmisskey/bash-install#readme](https://github.com/joinmisskey/bash-install#readme)

도메인 구매 및 Cloudflare 설정, 서버 확보는 여러분이 직접 준비해 주시기 바랍니다.

쉘 스크립트에 문제가 있으면 제작자(aqz)에게 알려주시면 감사하겠습니다.

설치 및 빌드

구축 안내서을 잘 읽어보세요.

ImageMagick 관련

ImageMagick이 필요하지 않습니다!

빌드가 실패하는 경우

Misskey를 빌드하기 위해서는 최소 2GB의 메모리가 필요하다는 것이 경험상 권장됩니다.
서버를 확장하는 방법도 있지만, PC에서 빌드하여 서버에 배포하는 방법도 있습니다.

왠지 잘 안 풀린다

• 구축 안내서을 잘 읽어보세요.
• node.js의 버전이 오래되었나요?
  • 새로운 버전으로 해봅시다.
• 설치나 빌드시 Error나 WARN 같은 것이 나올 수 있지만, 문제가 없는 경우도 있습니다.일단 npm start로 동작을 확인해 봅시다.
• node-gyp이 설치되지 않았나요?
  • apt install build-essential을 시도합니다.
  • 윈도우는 이 글도 참고해 보세요.
• 그래도 안 되면 처음부터 다시 구축 가이드의 절차에 따라 다시 시도해 보세요.

버전업 후 문제 발생

• 구축 가이드 및 릴리즈 노트를 잘 읽어보세요.
• Misskey 버전업 시에는 반드시 pnpm install이나 pnpm run migrate를 해주시기 바랍니다.그래도 해결되지 않으면 pnpm run clean-all && pnpm install을 시도하고, pnpm run build && pnpm run migrate && pnpm start를 시도해 보십시오.
• 그래도 안 되면 처음부터 다시 구축 가이드의 절차에 따라 다시 시도해 보세요.

---

설정

구축 안내서를 잘 읽어보세요.

.config/default.yml에서 설정을 합니다. .config/example.yml을 복사하여 주석에 따라 작성합니다.

(YAML 형식에서는 #부터 줄 끝까지는 주석으로 취급합니다.）

URL 및 포트 번호

URL과 포트 번호의 구조가 조금 이해하기 어려운 것 같습니다.

URL, 포트 및 TLS 인증서 설정(Port and TLS settings) part A: example.yml 설명

리비전 번호 85a0f69 시점의 . config/example.yml에 'Port and TLS settings'로 설명 그림과 함께 순서대로 적혀있으므로 설명 그림과 함께 설명되어 있으므로, 이를 따라 설정해 봅시다. 본문의 해설을 한글로 번역하면서 진행하겠습니다.

URL의 설정

# Final accessible URL seen by a user.
# 사용자가 최종적으로 접속하는 URL
url: https://example.tld/

**url: `에는 서버에 브라우저로 접속했을 때 주소창에 표시되는 **(하고 싶은)URL을 적습니다.

포트 및 인증서 설정

#   ┌───────────────────────┐
#───┘ Port and TLS settings └───────────────────────────────────
#### 포트 및 인증서 설정      ####################################
#
# Misskey supports two deployment options for public.
# Misskey는 두 가지 서버 개설 방법을 지원합니다.
#

# Option 1: With Reverse Proxy
# 방법 1 리버스 프록시 거치기
#
#                 +----- https://example.tld/ ------------+
#   +------+      |+-------------+      +----------------+|
#   | User | ---> || Proxy (443) | ---> | Misskey (3000) ||
#   +------+      |+-------------+      +----------------+|
#                 +---------------------------------------+
#
#   You need to setup reverse proxy. (eg. Nginx)
#   이 방법을 사용하려면 리버스 프록시(예: Nginx)를 설정해야 합니다.
#   You do not define 'https' section.
#   'https' 섹션(후술)은 설정하지 않고 주석 처리된 상태로 둡니다.

# Option 2: Standalone
# 방법 2 독립 실행형
#           (리버스 프록시를 거치지 않고, node의 프로세스에서 직접 사용자로부터 접근을 받습니다.)
#
#                 +- https://example.tld/ -+
#   +------+      |   +---------------+    |
#   | User | ---> |   | Misskey (443) |    |
#   +------+      |   +---------------+    |
#                 +------------------------+
#
#   You need to run Misskey as root.
#   이 방법을 사용하려면 Misskey를 루트(권한이 부여된 상태)로 실행해야 합니다.
#   You need to set Certificate in 'https' section.
#   'https' 섹션(후술)에서 인증서를 설정해야 합니다.

방법1 리버스 프록시를 거칠때

# To use option 1, uncomment below line.
# 옵션 1로 설정하는 경우 다음 줄을 주석 처리합니다 → 했습니다.
port: 3000    # A port that your Misskey server should listen.

위의 세 줄은 리버스 프록시를 거칠때의 이야기입니다. 이 예에서 Misskey는 포트 3000으로 통신합니다. 리버스 프록시에서는 이 포트 번호를 로컬 측 대상에 지정합니다.

방법 2 리버스 프록시를 거치지 않을 때

# To use option 2, uncomment below lines.
# 옵션 2로 설정하는 경우 아래 6줄을 주석 처리합니다 → 했습니다.
port: 443

https:
  # path for certification
  key: /etc/letsencrypt/live/example.tld/privkey.pem
  cert: /etc/letsencrypt/live/example.tld/fullchain.pem

위의 8줄은 리버스 프록시를 거치지 않았을 때의 이야기입니다. 포트 443(https)으로 사용자와 직접 통신합니다(포트 443을 이용하므로 Misskey의 프로세스에는 루트 권한이 필요합니다).

TLS 인증서를 별도로 발급받고, 발급받은 인증서의 디렉토리를 https:로 설정합니다. 여기서는 Let's Encrypt에서 example.tld에 대한 인증서를 발급한 예시입니다.

---

URL, 포트 및 TLS 인증서 설정(Port and TLS settings) part B: 전체 개요

example.yml의 설명문을 생략하면 default.yml의 포트와 TLS 인증서 설정은 다음과 같습니다.

방법1 리버스 프록시를 거칠때

url: https://example.tld/
port: 3000
# https:
#   # path for certification
#   key: /etc/letsencrypt/live/example.tld/privkey.pem
#   cert: /etc/letsencrypt/live/example.tld/fullchain.pem

방법2 리버스 프록시를 거치지 않고 직접 통신할 때

url: https://example.tld/
# port: 3000
https:
  # path for certification
  key: /etc/letsencrypt/live/example.tld/privkey.pem
  cert: /etc/letsencrypt/live/example.tld/fullchain.pem

---

npm start 및 접속 시 자주 발생하는 오류

npm start로 서버를 시작했지만, 그 후 문제가 발생하는 경우도 있습니다.

먼저, 구축 안내서 를 잘 읽어보세요.

YAML 오류 발생

default.yml 구문에 오류가 있을 수 있습니다. 줄머리에 여분의 공백은 없나요?

redis에 연결할 수 없음

redis-server가 실행되고 있습니까? 어떤 연결 수 제한에 도달하지 않았습니까?

11.20.2 이전 버전의 Misskey는 redis의 비밀번호를 풀 수 없습니다.다음 두 가지 사항을 확인하시기 바랍니다.

• redis에 비밀번호를 설정하지 않는다.
• default.yml의 redis:의 pass: 행을 주석 처리한다.

상단에 '개발용 빌드입니다'라고 적힌 빨간색 막대가 표시된다.

서버를 공개할 때는 반드시 production 빌드를 사용해야 합니다.

제품 빌드로 설정하려면 환경 변수를 NODE_ENV=production으로 설정하고 npm run build && npm start를 실행합니다.

신규 등록 불가

API에 접속할 수 없는 것 같습니다. default.yml의 시작 부분인 url:이 제대로 설정되어 있는지 확인합니다. Node.js의 버전과 설치 설정도 다시 한 번 꼼꼼히 확인해 봅시다.

또한 default.yml이 제대로 작성되어 있습니까?

타임라인 표시 문제 발생, 실시간으로 TL이 업데이트되지 않음

타임라인 불러오기에 실패하는 경우, mongoDB나 PostgreSQL의 버전이 오래된 것일 수 있습니다. PostgreSQL은 가급적 v13으로 업데이트해 주세요.

redis의 연결도 확인하는 것이 좋습니다. [→ redis에 접속할 수 없나요? 참조](#redis에 연결할 수 없음)

영원히 '재접속 중'이라고 오른쪽 하단에 표시되고, 실시간으로 TL이 업데이트되지 않는다.

프록시를 이용하고 있다면, 그것이 WebSocket 통신을 방해하고 있을 가능성이 있습니다.

오브젝트 스토리지 사용 시 오류 발생

오브젝트 스토리지의 권한 설정이 엄격하게 설정되어 있을 수 있습니다.'누구나 파일(객체)을 가져올 수 있음'으로 권한을 설정해 보시기 바랍니다. 또한, default.yml을 다시 한 번 확인해보시기 바랍니다.

S3 example (with CDN, custom domain)

S3 example (with CDN, custom domain)은 AWS의 기본 도메인이 아닌 자체 도메인으로 스토리지를 공개하고 싶은 경우의 설정입니다. endpoint와 공개 도메인이 동일한 서비스의 경우 S3 example처럼 baseUrl은 명시하지 않아도 되며, 또한 region 개념이 없는 서비스의 경우 region 라인은 필요하지 않습니다.

S3 호환 서비스 설정

Misskey에서는 오브젝트 스토리지 연결에 aws-sdk를 이용하고 있습니다. 아마존 S3와 호환되는 오브젝트 스토리지라면 사용할 수 있습니다.

각 서비스/소프트웨어의 설명서를 잘 읽고 설정해 보세요.

---

전혀 해결되지 않은 경우

다음 순서를 시도해 보세요.

1. Misskey의 문서를 잘 읽는다.
2. 구글에서 검색해 본다.
3. Misskey 저장소의 Issues를 검색해 본다(동일한 오류가 발생하거나, Misskey의 버그일 가능성도 있습니다).
4. 미스키 포럼을 검색해 본다.
5. 검색을 해도 잘 안 나오면 전문가에게 물어보세요.
   1. 포럼이나 Misskey의 Discord 서버 또는 고등어 통조림 공장(서버 관리자 공장)에서 물어보세요.
   2. 개발자(aqz나 shuiro)에게 리플이나 직접 글을 보내 물어보기