❓ Admin Frequently Asked Questions (FAQ) and Troubleshooting

This document provides solutions to common troubleshooting issues that may arise during the installation, deployment, and operation of the blog, as well as a guide to safely upgrading to the latest version.

🗄️ Q1. How do I safely upgrade to the latest version or restore my data?

To preserve database integrity and prevent unexpected build crashes, we strongly recommend following the safe upgrade procedures below.

1. Safe Upgrade and Verification Procedure (Recommended)

To prevent database schema mismatches or template conflicts, do not deploy immediately to your production server. Instead, perform verification in a test environment first (applicable to non-Git users as well).

1. Preserve Settings Backup:
   • Copy wrangler.backup.json and .dev.vars from your current development folder to a safe temporary location.
   • ※ Note: The .dev.vars file contains critical credentials (passwords, OAuth keys, etc.) but is excluded from Git tracking (.gitignore) for security. Therefore, it is easily lost when updating or pulling source code. Be sure to back it up.
2. Back Up Production Data:
   • Go to the Content Backup menu in your active blog admin panel and download the complete posts and settings backup file.
3. Clone/Download the New Version in an Isolated Folder:
   • Do not overwrite the existing folder. Download or clone the latest release source code in an entirely new directory.
4. Deploy a Temporary Test Server:
   • Navigate to the new folder, install dependencies (npm install), create a temporary database, and perform a test deployment.
5. Test Backup Restore:
   • Access the newly deployed test admin panel and load the backup file downloaded in Step 2. Verify thoroughly that all posts and configurations display correctly without errors.
6. Apply Upgrade to Production Server:
   • Only after validating that everything functions correctly on the test server, return to your original development folder, update the codebase (git pull or overwrite source), and run the individual app deployment commands (npm run deploy:blog, npm run deploy:admin) to complete the official upgrade.

2. Last Resort for Data Loss

• Using the npm run restore Command:
  • If the infrastructure settings or database are severely damaged and require a fresh restoration, use the backed-up wrangler.backup.json file as a last resort for data recovery to rebuild the entire infrastructure.

📂 Q2. What are the mandatory keys required when changing image storage to R2, Supabase, or ImageKit?

Below is a checklist of mandatory environment variables and configurations required when using each external image storage provider.

📊 Q3. Dashboard analytics charts display only demo data.

• Cause: If Google Analytics 4 (GA4) API environment variables are missing or invalid, placeholder demo data is shown to prevent dashboard crashes.
• Setup: Add the following environment variables to the Cloudflare Pages settings and redeploy:
  • GA4_PROPERTY_ID: Google Analytics Property ID
  • GA4_CLIENT_EMAIL: Google Cloud Service Account Email
  • GA4_PRIVATE_KEY: Google Service Account Private Key
• Caution: When writing GA4_PRIVATE_KEY in .dev.vars, ensure the entire key string is enclosed in double quotes (") so that line break codes (\n) are preserved correctly during parsing.

⚡ Q4. I cannot access the admin page, or some data sync seems to be missing after the initial setup deployment.

• Cause: Even if environment variable settings are successfully guided during the one-click setup, temporary network errors or system glitches may cause some encryption keys or secret variables (Secrets) to be partially missing or corrupted during deployment.
• Solution: Double-check the values in each app's .dev.vars file. Then, navigate to each folder and manually execute the deployment commands (npm run deploy:blog and npm run deploy:admin) once. The secret environment variables stored in your local .dev.vars will overwrite the environment variables on Cloudflare, resolving the issue.

🔒 Q5. An "Forbidden (IP Not Allowed)" or 403 Forbidden error occurs when accessing the admin page.

Due to the security specifications of this blog, the deployment script automatically detects the public IP address of your deployment PC and injects it as the allowed IP (ALLOWED_IP) into the Pages Secret.

⚠️ Admin Security Recommendation

• To prevent account hijacking and unauthorized access, it is strongly recommended to restrict admin access and writing operations on public networks (e.g., cafes, libraries) or untrusted public PCs.

💡 Situation-Specific Troubleshooting

• Situation A. Change in home or office IP address (e.g., router reboot):
  • Execute npm run deploy:admin once from your main development PC in the home/office. It will automatically detect the new public IP and redeploy, restoring your access immediately.
• Situation B. Relocating development environment to post from an external location:
  • Clone/download the project and execute a new setup deployment using your backed-up configuration file (wrangler.backup.json).
  • ※ Note: When returning to your original home/office, you must execute npm run deploy:admin again from your original development PC to restore the allowed IP back to your primary fixed IP.

🔐 Q6. Better Auth (social login or signup) errors or infinite login loops occur.

• Cause: Session verification fails and loops if authentication-related secrets are missing or incorrect.
• Solution:
  1. Check apps/blog/.dev.vars and ensure that BETTER_AUTH_SECRET is set to a secure random string of at least 32 characters.
  2. After correcting it, run npm run deploy:blog to overwrite and sync the secrets, which will restore normal authentication functionality.