mbround18/foundryvtt-docker

FoundryVTT Docker镜像文档

镜像概述和主要用途

本Docker镜像用于部署FoundryVTT虚拟桌面游戏平台。使用前需获取并激活FoundryVTT许可证，可通过官方购买页面获取。该镜像支持本地环境快速部署和Kubernetes集群部署，提供数据持久化存储方案，适用于个人或团队搭建虚拟桌面游戏环境。

核心功能和特性

• 多环境支持：兼容本地Docker运行和Kubernetes集群部署
• 数据持久化：通过卷挂载实现游戏数据持久化存储
• 灵活配置：支持环境变量自定义主机名、端口、SSL代理等参数
• 扩展能力：Kubernetes部署中集成SFTP服务，便于文件系统管理
• 安全支持：Kubernetes部署可配置TLS加密，保障数据传输安全

使用场景和适用范围

• 个人用户本地搭建FoundryVTT游戏服务器
• 小型团队通过Kubernetes集群部署高可用的FoundryVTT服务
• 需要持久化存储游戏数据和配置的场景
• 希望通过域名和SSL安全访问的生产环境部署

使用方法和配置说明

本地部署

基本本地运行

通过以下命令快速启动临时实例（容器停止后数据不保留）：

sh
docker run --rm -p 4444:4444 -e HOSTNAME="127.0.0.1" -e SSL_PROXY="false" docker.xuanyuan.run/mbround18/foundryvtt-docker:latest

带数据持久化的本地运行

使用卷挂载实现数据持久化（如需后台运行，将--rm替换为-d）：

sh
docker run --rm \
    -p 4444:4444 \
    -e HOSTNAME="127.0.0.1" \
    -e SSL_PROXY="false" \
    -v ${PWD}/data:/foundrydata \
    docker.xuanyuan.run/mbround18/foundryvtt-docker:latest

启动后访问 http://127.0.0.1:4444 即可进入平台。

本地部署后配置步骤

1. 访问 http://localhost:4444/uploader
2. 在新标签页打开FoundryVTT官网的已购许可证页面
3. 点击许可证旁的链接图标获取临时下载链接
4. 返回上传页面，粘贴临时链接并点击提交
5. 完成后访问 http://localhost:4444/ 进入FoundryVTT设置界面

Kubernetes部署

前提条件

• 已部署Kubernetes集群（推荐k3s，参考[***]
• 已安装kubectl并配置集群访问权限
• 拥有FoundryVTT激活许可证
• （可选）域名和DNS管理权限（用于HTTPS访问）

部署步骤

1. 创建命名空间

   创建foundryvtt命名空间，用于隔离资源：

   ${PWD}/00-namespace.yml

   yaml
   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: foundryvtt
     labels:
       name: foundryvtt
   

2. 创建持久卷声明

   申请持久化存储（示例配置适用于k3s默认的local-path存储类）：

   ${PWD}/01-persisted-volume-claim.yml

   yaml
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: foundryvtt-data-pv-claim
     namespace: foundryvtt
   spec:
     storageClassName: local-path
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 40G
   

3. 部署配置

   部署文件包含FoundryVTT主服务和SFTP服务（用于文件管理）：

   ${PWD}/02-deployment.yml

   yaml
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     namespace: foundryvtt
     name: foundryvtt
     labels:
       app: foundryvtt
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: foundryvtt
     template:
       metadata:
         labels:
           app: foundryvtt
       spec:
         containers:
           - name: foundryvtt-web
             image: docker.xuanyuan.run/mbround18/foundryvtt-docker:latest
             env:
               - name: APPLICATION_HOST
                 valueFrom:
                   secretKeyRef:
                     name: foundryvtt-env
                     key: APPLICATION_HOST
               - name: APPLICATION_PORT
                 value: "4444"
               - name: SSL_PROXY
                 value: "true"
             ports:
               - name: web
                 containerPort: 4444
             volumeMounts:
               - name: foundryvtt-data-persistent-storage
                 mountPath: /foundrydata
           - name: foundryvtt-ftp
             image: docker.xuanyuan.run/atmoz/sftp
             env:
               - name: FTP_USER
                 value: gm
               - name: FTP_PASS
                 valueFrom:
                   secretKeyRef:
                     name: foundryvtt-env
                     key: FTP_PASS
             args: ["$(FTP_USER):$(FTP_PASS):1001:95687:foundryvtt-data"]
             ports:
               - name: sftp
                 containerPort: 22
             volumeMounts:
               - name: foundryvtt-data-persistent-storage
                 mountPath: /home/gm/foundryvtt-data
         volumes:
           - name: foundryvtt-data-persistent-storage
             persistentVolumeClaim:
               claimName: foundryvtt-data-pv-claim
   

   注意：

   • SFTP服务首次登录后可能需要调整文件权限以支持读写
   • 当前SFTP配置需要节点独立IP，暂不支持通过ingress和域名访问

4. 创建环境变量配置

   在secrets目录创建环境变量文件：

   ${PWD}/secrets/env.txt

   txt
   APPLICATION_HOST=your.domain  # 替换为你的域名
   FTP_PASS=changeme             # 替换为SFTP密码
   

5. 创建服务

   定义Web服务和SFTP服务的访问方式：

   ${PWD}/03-web-service.yml

   yaml
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: foundryvtt-web
     labels:
       name: foundryvtt-web
     namespace: foundryvtt
   spec:
     selector:
       app: foundryvtt
     ports:
       - name: web
         port: 80
         targetPort: 4444
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: foundryvtt-ftp
     labels:
       name: foundryvtt-ftp
     namespace: foundryvtt
   spec:
     type: NodePort
     selector:
       app: foundryvtt
     externalIPs:
       - xx.xx.xx.xx  # 替换为节点IP
     ports:
       - port: 2222
         targetPort: 22
   

6. 配置Ingress

   （适用于k3s默认的traefik ingress控制器）：

   ${PWD}/04-ingress.yml

   yaml
   ---
   apiVersion: extensions/v1beta1
   kind: Ingress
   metadata:
     name: foundryvtt
     namespace: foundryvtt
     annotations:
       kubernetes.io/ingress.class: traefik
   spec:
     rules:
       - host: your.domain  # 替换为你的域名
         http:
           paths:
             - backend:
                 serviceName: foundryvtt-web
                 servicePort: web
     tls:
       - secretName: foundryvtt-web-tls-cert
   

7. 创建kustomization配置

   整合所有资源和密钥：

   ${PWD}/kustomization.yml

   yaml
   ---
   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   namespace: foundryvtt
   commonLabels:
     app: foundryvtt
   resources:
     - 00-namespace.yml
     - 01-persisted-volume-claim.yml
     - 02-deployment.yml
     - 03-web-service.yml
     - 04-ingress.yml
   secretGenerator:
     - name: foundryvtt-env
       env: secrets/env.txt
       type: Opaque
     - name: foundryvtt-web-tls-cert
       files:
         - secrets/tls.crt
         - secrets/tls.key
       type: "kubernetes.io/tls"
   

8. 生成TLS证书

   在secrets目录生成自签名证书（生产环境建议使用Let's Encrypt）：

   sh
   openssl req -new -newkey rsa:4096 -nodes -keyout secrets/tls.key -out secrets/tls.crt
   

   按提示填写信息，生成后会在secrets目录创建tls.key和tls.crt文件。

9. 配置DNS

   在DNS提供商（如CloudFlare）将域名解析至集群节点IP，可使用CNAME指向根域名或A记录直接指向节点IP。

10. 部署应用

    执行以下命令部署所有资源：

    sh
    kubectl apply -k .
    

11. 等待部署完成

    部署过程需几分钟，可通过kubectl get pods -n foundryvtt查看状态，当Pod状态为Running时表示部署完成。

Kubernetes部署后配置步骤

1. 访问 https://your.domain/uploader（替换为你的域名）
2. 登录FoundryVTT官网，进入已购许可证页面
3. 获取许可证临时下载链接并粘贴至上传页面
4. 点击提交，显示"Completed!!"后访问 https://your.domain/
5. 按常规流程完成FoundryVTT初始化设置

环境变量说明