Key Considerations for Migrating Legacy Programs like Discuz/Dedecms to New Environments

The difficulty in migrating legacy programs (Discuz, Dedecms, and various early PHP systems) lies in the fact that they often rely on older PHP versions and deprecated functions, making them incompatible with new environments running modern PHP.

The core issue in such migrations is not “data transfer,” but rather environment compatibility.

Most Common Issue: PHP Version Incompatibility

# ① First, confirm the original environment's PHP version (must be recorded before migration)
php -v
php -m | tr 'n' ' '
php -i | grep -iE 'upload_max_filesize|memory_limit|short_open_tag'

You must record “what version was used in the original environment” before migration. If you realize you don’t know after moving to the new environment, you’ll have to guess.

Two Viable Approaches

Do not expect to “upgrade the PHP version while migrating.” Legacy program migration is already complex; adding a version upgrade makes troubleshooting difficult.

# When multiple versions coexist, specify the version for this site individually
# Control panel environment: Select PHP version in site settings
# Manual environment: Confirm which php-fpm fastcgi_pass points to
grep fastcgi_pass /etc/nginx/conf.d/site.conf

Migration Steps

# ① Record original environment (version, extensions, config)
php -v > /tmp/env.txt; php -m >> /tmp/env.txt
mysqldump ... > db.sql

# ② Package program files (including all attachment directories)
tar -czf site.tar.gz -C /original_directory .

# ③ Install corresponding PHP version and extensions in new environment
# ④ Extract and import database
# ⑤ Modify database information in configuration files
# ⑥ Verify using hosts file
# ⑦ Switch DNS resolution

Configuration File Locations

# If location is unknown, search for database connection info
grep -rl 'dbhost|DB_HOST' /var/www/html --include='*.php' | head -10
grep -rn 'database_name' /var/www/html --include='*.php' | head -5

Post-Migration Checklist

# ① Ensure cache/data directories are writable
ls -ld /var/www/html/data /var/www/html/cache 2>/dev/null
ps aux | grep '[p]hp-fpm' | awk '{print $1}' | sort -u    # Web process user

# Fix ownership
chown -R www:www /var/www/html

# ② Pretty URLs (Nginx)
location / {
    try_files $uri $uri/ /index.php?$args;
}

# ③ Domains in database (replace if domain changed)
mysql -e "SELECT COUNT(*) FROM database.table WHERE field LIKE '%old_domain%';"
# Legacy program table prefixes vary, so confirm first

Security Precautions

A practical issue with legacy programs is that many have not received official updates for a long time and contain known vulnerabilities. Extra hardening is required after migration.

# Restrict backend access source
location ~ ^/admin/ {
    allow your_IP;
    deny all;
}

# Disable PHP execution in upload directories
location ~* ^/data/attachment/.*.php$ {
    deny all;
}

Restricting backend IP access is particularly valuable for legacy programs—low cost, yet the backend is often the primary attack target.

Decision Tree

Legacy Program Migration
├─ Record original environment before migration (PHP version + extensions) ← Most important
├─ New Environment
│  ├─ Install similar PHP version          ← Recommended, do not upgrade casually
│  └─ Match extensions to original environment
├─ Post-migration checks
│  ├─ Attachments/Images (domain-bound paths)
│  ├─ Cache directory writable
│  ├─ Pretty URLs (Nginx ignores .htaccess)
│  └─ Old domains in database
└─ Security (Priority for legacy programs)
   ├─ Restrict backend IP
   ├─ Disable execution in upload dirs
   └─ Consider upgrading to maintained software

Scenario Walkthrough: Frontend Shows Errors After Migration

Symptom: A Discuz-like program running for years is migrated to a new server.
After moving files and data via standard methods, the frontend displays fatal errors,
and the backend is inaccessible.

1. Analyze the error message →
   It indicates a language feature no longer supported in the current version.
   This confirms the issue is version-related, not data-related.
2. Confirm the highest supported version for this program →
   Legacy programs often only support older versions; installing the latest will cause errors.
3. Prepare the matching version in the new environment →
   Do not use the default version; deploy a compatible version separately.
4. Verify extension availability →
   Extensions relied upon by legacy programs are often not installed by default in new environments.
5. Handle version differences in data →
   Import may encounter charset or table format incompatibilities; handle in segments.
6. Verify and maintain rollback option →
   Keep the old environment available until the new environment passes all functional tests.

# Version consistency: The first hurdle in legacy migration
php -v | head -1
mysql --version

# Check for missing required extensions
php -m | grep -iE 'mysql|gd|mbstring|xml|curl'

# Charset issues during data import
mysqldump --default-character-set=old_charset dbname > dump.sql
sed -i 's/old_charset/new_charset/g' dump.sql

# Enable error display temporarily (revert after fixing)
tail -50 /www/wwwlogs/site_error.log

Root Cause: The new environment defaults to a newer language version,
which the legacy program does not support. Migration focused solely on “moving files and data,” ignoring version compatibility.

Two Key Takeaways:

• Determine the highest supported version of the legacy program first, then decide what to install in the new environment.
  Reversing this order leads to “moved but cannot open” scenarios, where version issues are often overlooked during troubleshooting.
• Keep the old environment until the new environment verification is complete.
  Compatibility issues with legacy programs are often cumulative; the value of a rollback option is greater than expected.

8 Common Pitfalls

1. Failing to record original environment version: Forced to guess in the new environment.
2. Installing latest PHP in new environment: Legacy programs fail to run.
3. Upgrading versions during migration: Makes troubleshooting difficult.
4. Neglecting pretty URL replication: Internal pages return 404.
5. Non-writable cache directory: Functional anomalies.
6. Changing domain without updating database: Attachment paths break.
7. Unrestricted backend access: Legacy backends are prime attack targets.
8. Ignoring long-term upgrades: Security debt accumulates.

Real Customer Feedback (From Cloud Market Reviews and Consultations for Similar Services)

The following excerpts are from real buyer reviews and consultations for similar operations services on Alibaba Cloud / Tencent Cloud / Huawei Cloud Cloud Markets (providers include our store and peers, provided for reference only, not fictional tickets):

10***09 2024-03-18 5.0 Convenient and stable | Clean interface | Comprehensive after-sales service (User did not fill in review content)