本文记录于 2021 年 9 月。

版本选择原因：

• Alibaba Cloud Linux 完全兼容 CentOS，相比于 CentOS 较短的生命周期，Alibaba Cloud Linux 3 将于 2029 年 4 月 30 日结束生命周期。

• Discuz! X3.4 不支持 PHP 8.0，安装时即报错，打开页面时一片空白。

• MySQL 8.0 和阿里云 RDS 的 MySQL 7.5 不支持 MyISAM，而数据表 pre_common_member_grouppm 和 pre_forum_post 使用联合主键且自动递增字段不是第一主键，使用 InnoDB 引擎创建表时会报“1075 - Incorrect table definition; there can be only one auto column and it must be defined as a key”错误，而擅自更改主键次序会影响业务逻辑。因此，在必须选择阿里云 RDS 的情况下，只能选择 MySQL 5.6。（2023年8月注：查看如何更改为 InnoDB）

• Discuz! X3.5 正式版尚未发布（截止发稿），即便发布，插件也可能不能得到及时更新。相比之下，X3.4 首个版本发布距今已有 4 年，相关第三方插件已经非常成熟。

完整升级步骤：

1. 备份原网站程序、RDS 数据库；

2. 购买新的 ECS、RDS，挂载磁盘，安装云监控；

3. 迁移（或还原）数据库到新的 RDS；
   

4. 安装宝塔面板并配置；

5. 安装 nginx 及 PHP；

6. 创建网站、配置 SSL、伪静态、防盗链、可写目录禁执行等（.conf）；

7. 配置 hosts；

8. 上传原网站程序到新的站点目录下；

9. 按 Discuz! X 升级文档升级 X3.2 至 X3.4；详情见下文 ↓；

10. 配置 OSS、Redis、更新缓存等；

11. 测试论坛基本功能是否正常；检查附件是否正常显示；全面检查控制台配置；

12. 逐个开启插件并检查兼容性；

13. 按二开备忘录逐个按需进行二开；

14. 逐个修改调用论坛接口的项目及直接调用论坛数据库的项目；

15. 调试 MAGAPP 接口；

16. 尝试强制 https 访问；
    

17. 将以上所有修改后的程序保留备份；发布升级公告并关闭论坛；重复以上步骤；修改域名解析；开启论坛；
    

18. 配置 IP 封禁、定时器、日志、自动备份、配置其它 ECS 的 hosts 等；

19. 查看搜索引擎中收录的地址，是否有无法访问的情况；
    

20. 尝试将历史遗留的本地附件全部转移到 OSS；

21. 参这篇文章，可能有其它需要配置的地方。
    

Discuz! X 升级步骤及注意点：

• 升级前务必先修改 ./config/ 目录下的数据库/缓存连接信息，以防出现新站连接老库的情况；

• 按官方文档进行升级；
  

• 【问题】运行到 ./install/update.php?step=data&op=notification 时白屏。

  【排查】尝试切换到 PHP 5.6 后成功（但该版本过于陈旧不能使用）；尝试升级 CPU 和内存 PHP 7.4 上升级仍不成功。

  【原因】DB::result_first() 方法不对 SQL 语句追加“limit 1”，而是 SELECT 所有记录后在 PHP 端取第一条数据；

  【解决】打开文件 update.php，查找 elseif($_GET['op'] == 'notification')，该节点的功能是在表 home_notification 中查找 category <= 0 的数据并修复它，如果数据库中所有 category 都大于 0，直接注释其内部 if 代码段继续升级即可（或改为 if(false && ...)）。

• 【问题】发布主题遇到错误：(1062) Duplicate entry '*' for key 'pid'

  【原因】forum_post 中的 pid 不是自动增长的，而是由表 forum_post_tableid 中自动增长的 pid 生成的。如果生成的 pid 值已在 forum_post 表中存在，则会出现此错误。

  【解决】迁移数据库时应关闭论坛，以防止 forum_post 表有新数据插入。

• 【问题】打开帖子页面 ./thread-***-1-1.html 显示 404 Not Found，而 ./forum.php?mod=viewthread&tid=*** 可以正常打开

  【原因】未配置伪静态（可在宝塔面板中选择）

• 【问题】打开 UCenter 时报错：UCenter info: MySQL Query Error SQL:SELECT value FROM [Table]vars WHERE name='noteexists'

  【解决】打开文件 ./uc_server/data/config.inc.php 配置数据库连接

• 【问题】打开登录 UCenter 后一片空白

  【解决】将目录 ./uc_server/data/ 设为可写

• 需要将原来安装的插件文件移回 ./source/plugin/ 目录，并设置可写；

• 界面-表情管理，界面-编辑器设置-Discuz!代码

后续 Discuz! X3.4 R 小版本升级注意事项：

1. 确认插件是否支持新版本（如短信通）

2. 先创建一个新网站测试二开代码

3. 保留 /config/、/data/、/uc_client/data/、/uc_server/data/、/source/plugin/，其它移入 old

4. 上传文件

5. 移回其它需要的文件，如：

6. -- 勋章/loading/logo/nv 等：/static/image/common/

7. -- 表情：/static/image/smiley/

8. -- 水印：/static/image/common/watermark.*

9. -- 风格：/template/default/style/t2/nv.png 等

10. -- 默认头像：/uc_server/images/noavatar_***.gif

11. -- 根目录 favicon.ico 等
    

12. -- 及其它非 DZ 文件

13. 再次检查可写目录的写入权限和禁止运行 PHP 效果。

JavaScript API GL v1.0 是基于 WebGL 全新开发的地图 API 接口。为了方便开发者迁移升级，大部份接口向下兼容。目前 GL v1.0 版本接口包含了 3D 地图的渲染、基本控件、覆盖物。在后面的版本中，将对原 v2.0、v3.0 中的核心功能进行补全。

JavaScript API GL 版本对手机性能要求较高，不建议在移动端调用。若涉及移动端 JS 服务调用，请使用 JavaScript API v3.0 版本。

JavaScript API GL v1.0 基于 WebGL 开发，对于用户的浏览器环境有兼容性要求。需要完整支持 WebGL 的现代浏览器来支持渲染。对于 WebGL 支持欠佳的浏览器会降级为 Canvas 绘制，若仍然存在兼容性问题，则会降级到瓦片图渲染。确保不同浏览器环境的用户都可以完成地图的基本渲染。

参考：http://lbsyun.baidu.com/index.php?title=jspopularGL/guide/usage

本文使用 Oracle 官方提供的 MySql.EntityFrameworkCore，如使用 Pomelo.EntityFrameworkCore.MySql 请移步。

MySql.EntityFrameworkCore 是 MySql.Data.EntityFrameworkCore 的升级版

本文以 Visual Studio 2019、ASP.NET Core 5.0 开发环境为例。

1. 新建 ASP.NET Core Web 应用程序。

2. 安装 NuGet 包：

   MySql.EntityFrameworkCore
   

   Microsoft.EntityFrameworkCore.Design

   

3. 根据已有数据库创建数据模型。在 NuGet 的程序包管理（Package Manager）控制台中（PowerShell）执行命令：

   Scaffold-DbContext "server=数据库服务器;port=3306;user=数据库用户名;password=数据库密码;database=数据库名" MySql.EntityFrameworkCore -OutputDir Data -f

   .Net Core CLi：

   dotnet ef dbcontext scaffold "server=数据库服务器;port=3306;user=数据库用户名;password=数据库密码;database=数据库名" MySql.EntityFrameworkCore -o Data -f

4. 搞定。

注：开发环境和生产环境都不需要安装 Connector/NET，只需要安装 ASP.NET Core。

补充：其它数据库提供程序请参考：https://docs.microsoft.com/zh-cn/ef/core/providers/

更多高级用法请参考官方文档。

喜欢“数据库优先”的朋友会发现，一旦 nuget 中将 MySql.Data 与 MySql.Data.EntityFramework 升级到版本超过 8.0.19，将无法正常打开 .edmx 文件进行从数据库更新模型。这个问题从 8.0.20 开始出现，在经过等待试验后续多个更新版本后，笔者认为 Oracle 官方不会再针对 8.0.20 及以后的版本支持可视化更新实体模型。

于是面临两个选择：退回到 8.0.19 版本，或使用其它数据库连接组件（如 Pomelo）。

使用其它组件将会更改映射的属性名称，对 Include 延时加载等机制也会发生改变，对于代码量比较大的项目修改成本还是比较大的。那么用回 8.0.19 呢？

在服务器上卸载 8.0.20+ 版本的 mysql-connector-net，安装 8.0.19 版本，重启 IIS 或重启服务器。

项目中，MySql.Data 与 MySql.Data.EntityFramework 也降至 8.0.19，发布后发现，仍然提示：

未能加载文件或程序集“MySql.Data.EntityFramework, Version=8.0.19.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d”或它的某一个依赖项。找到的程序集清单定义与程序集引用不匹配。 (异常来自 HRESULT:0x80131040)

几个月来，我一直认为是服务器上的高版本 mysql-connector-net 没有卸载干净，今天才发现原因是新发布的项目 bin 目录中的 MySql.Data.EntityFramework.dll 版本号仍然高于 8.0.19。手动替换成 8.0.19 后可正常访问。

既然 NuGet 已经将 MySql.Data.EntityFramework 的版本降至 8.0.19，而且 web.config 中所有的版本号也都一致，解决方案的 packages 目录下的也只有 MySql.Data.EntityFramework.8.0.19 这一个版本，甚至连项目源代码中的 bin 目录下的该文件版本也是 8.0.19，可发布后的 MySql.Data.EntityFramework.dll 版本却仍高于 8.0.19？

于是在解决方案中找到以下路径：

\obj\Release\Package\PackageTmp\bin\MySql.Data.EntityFramework.dll

重新发布时，这个文件并没有按照 NuGet 中的版本来覆盖，因此只需要在发布前删除整个 \obj\ 目录再次发布即可解决问题。

[root ~]# yum update xxx
Loaded plugins: security
Setting up Update Process
http://mirrors.aliyun.com/centos/6/os/x86_64/repodata/repomd.xml: [Errno 14] PYCURL ERROR 22 - "The requested URL returned error: 404 Not Found"
Trying other mirror.
To address this issue please refer to the below wiki article

https://wiki.centos.org/yum-errors

If above article doesn't help to resolve this issue please use https://bugs.centos.org/.

http://mirrors.aliyuncs.com/centos/6/os/x86_64/repodata/repomd.xml: [Errno 12] Timeout on http://mirrors.aliyuncs.com/centos/6/os/x86_64/repodata/repomd.xml: (28, 'connect() timed out!')
Trying other mirror.
http://mirrors.cloud.aliyuncs.com/centos/6/os/x86_64/repodata/repomd.xml: [Errno 14] PYCURL ERROR 22 - "The requested URL returned error: 404 Not Found"
Trying other mirror.
Error: Cannot retrieve repository metadata (repomd.xml) for repository: base. Please verify its path and try again

售后工程师:

您好，CentOS 6 已经停止技术支持通知  新购实例或者旧有的Centos 6 操作系统会导致yum安装失败，相关公告请见下面内容；

公告：CentOS 6 停止技术支持通知  

这边建议您考虑将数据备份一下，升级至Centos 7 版本。如果一定要使用，需要手动切换源，您可以将由原的yum 源做下备份，对/etc/yum.repos.d 内容进行清空处理，然后参考下面的教程做下源的更换处理。

教程：CentOS 6 EOL 如何切换源

有其他咨询，您继续反馈

简言之，对照自己的版本号，将文件 /etc/yum.repos.d/CentOS-Base.repo 与 /etc/yum.repos.d/epel.repo 的内容替换成教程中的内容即可。

报错：

HTTP Error 500.30 - ASP.NET Core app failed to start

Common solutions to this issue:

• The app failed to start

• The app started but then stopped

• The app started but threw an exception during startup

Troubleshooting steps:

• Check the system event log for error messages

• Enable logging the application process' stdout messages

• Attach a debugger to the application process and inspect

For more information visit: https://go.microsoft.com/fwlink/?LinkID=2028265

解决：

直接运行网站根目录的 .exe 启动文件可以找到答案。

一个常见的原因是：因 nuget 包升级（特别是需要服务器端安装组件的包）导致的发布后仍然是低版本的包，删除项目中的 /obj/ 目录重新发布即可。

在升级 kernel 后若无法启动系统，网站无法打开，SSH 无法连接，无法 ping 通。

使用 VNC 进入操作界面：

一种界面是可选择次新的内核版本：

应该能正常启动。

另一种界面提示：

Give root password for maintenance

输入密码后可启动。

阿里云工程师的建议：

1、当前默认是以最新内核启动的，由于新版内核文件存在异常无法正常运行，在手动选择低内核版本启动后，可以先更改下默认内核引导顺序，配置默认使用低版本内核运行，避免重启再次出现问题。 修改内核引导顺序 https://help.aliyun.com/knowledge_detail/41463.html 2、升级内核本身属于高危操作，建议操作前先做好快照备份，同时更新时可以参考下文档方案 避免Linux实例升级内核系统无法启动的方法 https://help.aliyun.com/knowledge_detail/59360.html

本教程教你如何升级 ASP.NET 项目中的 MySql.Data 和服务器安装的 Connector/NET 版本至 8.0.18。

使用 MySQL Application Configuration 升级 MySql.Data

双击打开 .edmx 文件后，解决方案资源管理器上会有 MySQL Application Configuration 的图标。（如果没有，点开“从数据库更新模型”一下即可）

勾选“Use MySQL with Entity Framework”，安装完成。

完成后发现，Nuget 中会自动安装或升级下面两个组件：

MySql.Data  8.0.18

MySql.Data.EntityFramework  8.0.18

并且在 Web.config 中会自动添加以下节点：

<system.data>
  <DbProviderFactories>
    <remove invariant="MySql.Data.MySqlClient" />
    <add name="MySQL Data Provider" invariant="MySql.Data.MySqlClient" description=".Net Framework Data Provider for MySQL" type="MySql.Data.MySqlClient.MySqlClientFactory, MySql.Data, Version=8.0.18, Culture=neutral, PublicKeyToken=c5687fc88969c44d" />
  </DbProviderFactories>
</system.data>

这段代码使 MySql.Data 8.0.18 的项目能够兼容运行在 Connector/NET 6.10.x 环境中。方便我们挨个升级服务器上的项目。

8.0.18 已经不再需要 MySql.Data.Entity 组件了，可以从 Nuget 中手动卸载。

在数据库连接字符串可设置是否将 tinyint(1) 映射为 bool，否则为 sbyte：

TreatTinyAsBoolean=false/true

tinyint(1) 一般用于表示 bool 型字段，存储内容为 0 或 1，但有时候也用来存储其它数字。

以 Discuz! 的表 pre_forum_post 为例，字段 first 和 invisible 都是 tinyint(1)，但 first 只储存 0 和 1，invisible 却有 -1、-5 之类的值。

因此我们一般设置 TreatTinyAsBoolean=false，程序中 first 与 invisible 均以 sbyte 处理。

设置 TreatTinyAsBoolean=true 后，EF 或 EF Core 自动将该类型映射为 bool，方便在程序中作进一步处理。

一旦设置 TreatTinyAsBoolean=true，那么所有查询结果中 tinyint(1) 字段的返回值永远只有 1 和 0（即 True/False），即使真实值为 -1，也返回 1。

因为我们必须在确保所有的 tinyint(1) 类型字段都仅表示布尔值是才设置 TreatTinyAsBoolean=true。

一旦部分 tinyint(1) 类型字段用于存放 0 和 1 以外的数，那么就应该设置 TreatTinyAsBoolean=false。

在数据库优先的项目中，以 TreatTinyAsBoolean=false 生成数据模型后，可将明确为布尔类型的字段改为 bool。列出 MySQL 数据库中所有表所有字段中类型为 tinyint(1) 的字段值

以 .edmx 为例：

在项目中搜索该字段名，在搜索结果中找到 .edmx 文件中的两处。

.edmx 文件中的注释已经表明其包含 SSDL、CSDL、C-S mapping 三块内容，

在 SSDL content 下方找到该字段：

<Property Name="字段名" Type="tinyint" Nullable="***" />

改为

<Property Name="字段名" Type="bool" Nullable="***" />

在 CSDL content 下方找到该属性：

<Property Name="属性名" Type="SByte" Nullable="***" />

改为

<Property Name="属性名" Type="Boolean" Nullable="***" />

在解决方案管理器中展开 .edmx ->库名.tt -> 表名.cs 文件，

将模型类中的属性

public sbyte invisible { get; set; }

改为

public bool invisible { get; set; }

或 sbyte? 改为 bool?。

在 EF Core 中，直接打开对应数据表的 .cs 文件，更改属性类型即可。

相关报错：

错误: 指定的成员映射无效。类型中的成员的类型“Edm.SByte[Nullable=False,DefaultValue=]”与类型中的成员的“MySql.bool[Nullable=False,DefaultValue=]”不兼容。

InvalidOperationException: The property '***' is of type 'sbyte' which is not supported by the current database provider. Either change the property CLR type, or ignore the property using the '[NotMapped]' attribute or by using 'EntityTypeBuilder.Ignore' in 'OnModelCreating'.

尝试先连接一次能解决此问题（概率），非常的莫名其妙：

using Data.Discuz.db_bbs2021Context dbd = new();
var conn = dbd.Database.GetDbConnection();
conn.Open();
conn.Close();

参考：

https://mysqlconnector.net/connection-options/

https://stackoverflow.com/questions/6656511/treat-tiny-as-boolean-and-entity-framework-4

2023年1月注：本文适用于 Pomelo.EntityFrameworkCore.MySql 6.0，升级到 7.0 后会出现：

System.InvalidOperationException:“The 'sbyte' property could not be mapped to the database type 'tinyint(1)' because the database provider does not support mapping 'sbyte' properties to 'tinyint(1)' columns. Consider mapping to a different database type or converting the property value to a type supported by the database using a value converter. See https://aka.ms/efcore-docs-value-converters for more information. Alternately, exclude the property from the model using the '[NotMapped]' attribute or by using 'EntityTypeBuilder.Ignore' in 'OnModelCreating'.”

解决方法：https://xoyozo.net/Blog/Details/the-sbyte-property-could-not-be-mapped-to-the-database-type-tinyint-1

安装最新的：MySQL for Visual Studio

安装版本一致的：MySQL Connector Net、MySql.Data 和 MySql.Data.Entity

若仍闪退，在 MySQL Application Configuration 中勾选 Entity Framework 的 Use MySQL with Entity Framework

或直接升级 MySql.Data 到 8.x